ways_to_contribute.rst 11 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115116117118119120121122123124125126127128129130131132133134135136137138139140141142143144145146147148149150151152153154155156157158159160161162163164165166167168169170171172173174175176177178179180181182183184185186187188189190191192193194195196197198199200201202203204205206207208209210211212213214215216217218219
  1. .. _doc_ways_to_contribute:
  2. Ways to contribute
  3. ==================
  4. Godot Engine is a non-profit, community-driven free and open source project.
  5. Almost all (but our lead dev Juan, more on that below) developers are working
  6. *pro bono* on their free time, out of personal interest and for the love of
  7. creating a libre engine of exceptional quality.
  8. This means that to thrive, Godot needs as many users as possible to get
  9. involved by contributing to the engine. There are many ways to contribute to
  10. such a big project, making it possible for everybody to bring something
  11. positive to the engine, regardless of their skill set:
  12. - **Be part of the community.** The best way to contribute to Godot and help
  13. it become ever better is simply to use the engine and promote it by
  14. word-of-mouth, in the credits or splash screen of your games, blog posts, tutorials,
  15. videos, demos, gamedev or free software events, support on the Q&A, IRC,
  16. forums, Discord, etc. Participate!
  17. Being a user and advocate helps spread the word about our great engine,
  18. which has no marketing budget and can therefore only rely on its community
  19. to become more mainstream.
  20. - **Make games.** It's no secret that, to convince new users and especially the
  21. industry at large that Godot is a relevant market player, we need great games
  22. made with Godot. We know that the engine has a lot of potential, both for 2D
  23. and 3D games, but given its young age we still lack big releases that will
  24. draw attention to Godot. So keep working on your awesome projects, each new
  25. game increases our credibility on the gamedev market!
  26. - **Get involved in the engine's development.** This can be by contributing
  27. code via pull requests, testing the development snapshots or directly the
  28. git *master* branch, report bugs or suggest enhancements on the issue
  29. tracker, improve the official documentation (both the class reference and
  30. tutorials) and its translations.
  31. The following sections will cover each of those "direct" ways
  32. of contributing to the engine.
  33. - **Donate.** Godot is a non-profit project, but it can still benefit from
  34. user donations for many things. Apart from usual expenses such as hosting
  35. costs or promotional material on events, we also use donation money to
  36. acquire hardware when necessary (e.g. we used donation money to buy a
  37. MacBook Pro to implement Retina/HiDPI support and various other
  38. macOS-related features).
  39. Most importantly, we also used donation money to hire core developers so they
  40. can work full-time on the engine. Even with a low
  41. monthly wage, we need a steady donation income to continue doing this, which
  42. has been very beneficial to the project so far. So if you want to donate
  43. some money to the project, check `our website <https://godotengine.org/donate>`_
  44. for details.
  45. Contributing code
  46. -----------------
  47. The possibility to study, use, modify and redistribute modifications of the
  48. engine's source code are the fundamental rights that
  49. Godot's `MIT <https://tldrlegal.com/license/mit-license>`_ license grants you,
  50. making it `free and open source software <https://en.wikipedia.org/wiki/Free_and_open-source_software>`_.
  51. As such, everyone is entitled to modify
  52. `Godot's source code <https://github.com/godotengine/godot>`_, and send those
  53. modifications back to the upstream project in the form of a patch (a text file
  54. describing the changes in a ready-to-apply manner) or - in the modern workflow
  55. that we use - via a so-called "pull request" (PR), i.e. a proposal to directly
  56. merge one or more Git commits (patches) into the main development branch.
  57. Contributing code changes upstream has two big advantages:
  58. - Your own code will be reviewed and improved by other developers, and will be
  59. further maintained directly in the upstream project, so you won't have to
  60. reapply your own changes every time you move to a newer version. On the
  61. other hand it comes with a responsibility, as your changes have to be
  62. generic enough to be beneficial to all users, and not just your project; so
  63. in some cases it might still be relevant to keep your changes only for your
  64. own project, if they are too specific.
  65. - The whole community will benefit from your work, and other contributors will
  66. behave the same way, contributing code that will be beneficial to you. At
  67. the time of this writing, more than 1000 developers have contributed code
  68. changes to the engine!
  69. To ensure good collaboration and overall quality, the Godot developers
  70. enforce some rules for code contributions, for example regarding the style to
  71. use in the C++ code (indentation, brackets, etc.) or the Git and PR workflow.
  72. A good place to start is by searching for issues tagged as `junior jobs <https://github.com/godotengine/godot/issues?q=is%3Aissue+is%3Aopen+label%3A%22junior+job%22>`_
  73. (or `Hacktoberfest <https://github.com/godotengine/godot/issues?utf8=%E2%9C%93&q=is%3Aissue+is%3Aopen+label%3AHacktoberfest+>`_ during October) on GitHub.
  74. .. seealso:: Technical details about the PR workflow are outlined in a
  75. specific section, :ref:`doc_pr_workflow`.
  76. Details about the code style guidelines and the ``clang-format``
  77. tool used to enforce them are outlined in
  78. :ref:`doc_code_style_guidelines`.
  79. All pull requests must go through a review process before being accepted.
  80. Depending on the scope of the changes, it may take some time for a maintainer
  81. responsible for the modified part of the engine to provide their review.
  82. We value all of our contributors and ask them to be patient in the meantime,
  83. as it is expected that in an open source project like Godot, there is going to be
  84. way more contributions than people validating them.
  85. To make sure that your time and efforts aren't wasted, it is recommended to vet the idea
  86. first before implementing it and putting it for a review as a PR. To that end, Godot
  87. has a `proposal system <https://github.com/godotengine/godot-proposals>`_. Its
  88. usage is encouraged to plan changes and discuss them with the community. Implementation
  89. details can also be discussed with other contributors on the `Godot Contributors Chat <https://chat.godotengine.org/>`_.
  90. .. note:: Proposals are only required when working on an enhancement or a new feature.
  91. Bug reports are sufficient for fixing issues.
  92. Testing and reporting issues
  93. ----------------------------
  94. Another great way of contributing to the engine is to test development releases
  95. or the development branch and to report issues. It is also helpful to report
  96. issues discovered in stable releases, so that they can be fixed in
  97. the development branch and in future maintenance releases.
  98. Testing development versions
  99. ~~~~~~~~~~~~~~~~~~~~~~~~~~~~
  100. To help with the testing, you have several possibilities:
  101. - Compile the engine from source yourself, following the instructions of the
  102. :ref:`Compiling <toc-devel-compiling>` page for your platform.
  103. - Test official pre-release binaries when they are announced (usually on the
  104. blog and other community platforms), such as alpha, beta and release candidate (RC) builds.
  105. - Test "trusted" unofficial builds of the development branch; just ask
  106. community members for reliable providers. Whenever possible, it's best to
  107. use official binaries or to compile yourself though, to be sure about the
  108. provenance of your binaries.
  109. As mentioned previously, it is also helpful to keep your eyes peeled for
  110. potential bugs that might still be present in the stable releases, especially
  111. when using some niche features of the engine which might get less testing by
  112. the developers.
  113. Filing an issue on GitHub
  114. ~~~~~~~~~~~~~~~~~~~~~~~~~
  115. Godot uses `GitHub's issue tracker <https://github.com/godotengine/godot/issues>`_
  116. for bug reports and enhancement suggestions. You will need a GitHub account to
  117. be able to open a new issue there, and click on the "New issue" button.
  118. When you report a bug, you should keep in mind that the process is similar
  119. to an appointment with your doctor. You noticed *symptoms* that make you think
  120. that something might be wrong (the engine crashes, some features don't work as
  121. expected, etc.). It's the role of the bug triaging team and the developers to
  122. then help make the diagnosis of the issue you met, so that the actual cause of
  123. the bug can be identified and addressed.
  124. You should therefore always ask yourself: what is relevant information to
  125. give so that other Godot contributors can understand the bug, identify it and
  126. hopefully fix it. Here are some of the most important infos that you should
  127. always provide:
  128. - **Operating system.** Sometimes bugs are system-specific, i.e. they happen
  129. only on Windows, or only on Linux, etc. That's particularly relevant for all
  130. bugs related to OS interfaces, such as file management, input, window
  131. management, audio, etc.
  132. - **Hardware.** Sometimes bugs are hardware-specific, i.e. they happen
  133. only on certain processors, graphic cards, etc. If you are able to,
  134. it can be helpful to include information on your hardware.
  135. - **Godot version.** This is a must have. Some issues might be relevant in the
  136. current stable release, but fixed in the development branch, or the other
  137. way around. You might also be using an obsolete version of Godot and
  138. experiencing a known issue fixed in a later version, so knowing this from
  139. the start helps to speed up the diagnosis.
  140. - **How to reproduce the bug.** In the majority of cases, bugs are
  141. reproducible, i.e. it is possible to trigger them reliably by following some
  142. steps. Please always describe those steps as clearly as possible, so that
  143. everyone can try to reproduce the issue and confirm it. Ideally, make a demo
  144. project that reproduces this issue out of the box, zip it and attach it to
  145. the issue (you can do this by drag and drop).
  146. Even if you think that the issue is trivial to reproduce, adding a minimal
  147. project that lets reproduce it is a big added value. You have to keep in
  148. mind that there are thousands of issues in the tracker, and developers can
  149. only dedicate little time to each issue.
  150. When you click the "New issue" button, you should be presented with a text area
  151. prefilled with our issue template. Please try to follow it so that all issues
  152. are consistent and provide the required information.
  153. Contributing to the documentation
  154. ---------------------------------
  155. There are two separate resources referred to as "documentation" in Godot:
  156. - **The class reference.** This is the documentation for the complete Godot
  157. API as exposed to GDScript and the other scripting languages. It can be
  158. consulted offline, directly in Godot's code editor, or online at
  159. :ref:`Godot API <toc-class-ref>`.
  160. To contribute to the class reference, you have to edit the
  161. `doc/base/classes.xml` in Godot's Git repository, and make a pull request.
  162. See :ref:`doc_updating_the_class_reference` for more details.
  163. - **The tutorials and engine documentation and its translations.** This is the part you are reading
  164. now, which is distributed in the HTML, PDF and EPUB formats. Its contents
  165. are generated from plain text files in the reStructured Text (rst) format,
  166. to which you can contribute via pull requests on the
  167. `godot-docs <https://github.com/godotengine/godot-docs>`_ GitHub repository.
  168. See :ref:`doc_documentation_guidelines` for more details.
  169. Contributing translations
  170. -------------------------
  171. To make Godot accessible to everyone, including users who may prefer resources
  172. in their native language instead of English, our community helps translate both
  173. the Godot editor and its documentation in many languages.
  174. See :ref:`doc_editor_and_docs_localization` for more details.