.github/CONTRIBUTING.md

   1 # Contributing
   2
   3 Contributions are welcome! Here's how you can help:
   4
   5 - [Contributing code](#code)
   6 - [Reporting issues](#issues)
   7 - [Requesting features](#feature-requests)
   8 - [Translating](#translations)
   9 - [Donating](#donations)
  10
  11 ## Code
  12
  13 1. [Fork](https://help.github.com/articles/fork-a-repo/) the repository and
  14    [clone](https://help.github.com/articles/cloning-a-repository/) your fork.
  15
  16 2. Before you start coding, consider opening an
  17    [issue on Github](https://github.com/luanti-org/luanti/issues) to discuss the
  18    suitability and implementation of your intended contribution with the core
  19    developers.
  20
  21    Any Pull Request that isn't a bug fix and isn't covered by
  22    [the roadmap](../doc/direction.md) will be closed within a month unless it
  23    receives a concept approval from a Core Developer. For this reason, it is
  24    recommended that you open an issue for any such pull requests before doing
  25    the work, to avoid disappointment.
  26
  27    You may also benefit from discussing on our IRC development channel
  28    [#minetest-dev](http://www.minetest.net/irc/). Note that a proper IRC client
  29    is required to speak on this channel.
  30
  31 3. Start coding!
  32     - Refer to the
  33       [Lua API](https://github.com/luanti-org/luanti/blob/master/doc/lua_api.md),
  34       [Developer Wiki](https://dev.luanti.org/) and other
  35       [documentation](https://github.com/luanti-org/luanti/tree/master/doc).
  36     - Follow the [C/C++](https://dev.luanti.org/Code_style_guidelines) and
  37       [Lua](https://dev.luanti.org/Lua_code_style_guidelines) code style guidelines.
  38     - Check your code works as expected and document any changes to the Lua API.
  39     - To avoid conflicting changes between contributions, do not do the following manually. They will be done before each release.
  40       - Run `updatepo.sh` or update `luanti.po{,t}` even if your code adds new translatable strings.
  41       - Update `minetest.conf.example` and `settings_translation_file.cpp` even if your code adds new core settings.
  42
  43 4. Commit & [push](https://help.github.com/articles/pushing-to-a-remote/) your changes to a new branch (not `master`, one change per branch)
  44     - Commit messages should:
  45         - Use the present tense.
  46         - Be descriptive. See the commit messages by core developers for examples.
  47     - The first line should:
  48         - Start with a capital letter.
  49         - Be a compact summary of the commit.
  50         - Preferably have less than 70 characters.
  51         - Have no full stop at the end.
  52     - The second line should be empty.
  53     - The following lines should describe the commit, starting a new line for each point.
  54
  55 5. Once you are happy with your changes, submit a pull request.
  56      - Open the [pull-request form](https://github.com/luanti-org/luanti/pull/new/master).
  57      - Add a description explaining what you've done (or if it's a
  58        work-in-progress - what you need to do).
  59      - Make sure to fill out the pull request template.
  60
  61 ### A pull-request is considered merge-able when:
  62
  63 1. It follows [the roadmap](../doc/direction.md) in some way and fits the whole
  64    picture of the project.
  65 2. It works.
  66 3. It follows the code style for
  67    [C/C++](https://dev.luanti.org/Code_style_guidelines) or
  68    [Lua](https://dev.luanti.org/Lua_code_style_guidelines).
  69 4. The code's interfaces are well designed, regardless of other aspects that
  70    might need more work in the future.
  71 5. It uses protocols and formats which include the required compatibility.
  72
  73 ## Issues
  74
  75 If you experience an issue, we would like to know the details - especially when
  76 a stable release is on the way.
  77
  78 1. Do a quick search on GitHub to check if the issue has already been reported.
  79 2. Is it an issue with the Minetest *engine*? If not, report it
  80    [elsewhere](http://www.minetest.net/development/#reporting-issues).
  81 3. [Open an issue](https://github.com/luanti-org/luanti/issues/new) and describe
  82    the issue you are having - you could include:
  83      - Error logs (check the bottom of the `debug.txt` file).
  84      - Screenshots.
  85      - Ways you have tried to solve the issue, and whether they worked or not.
  86      - Your Luanti version and the content (games, mods or texture packs) you have installed.
  87      - Your platform (e.g. Windows 10 or Ubuntu 15.04 x64).
  88
  89 After reporting you should aim to answer questions or clarifications as this
  90 helps pinpoint the cause of the issue (if you don't do this your issue may be
  91 closed after 1 month).
  92
  93 ## Feature requests
  94
  95 Feature requests are welcome but take a moment to see if your idea follows
  96 [the roadmap](../doc/direction.md) in some way and fits the whole picture of
  97 the project. You should provide a clear explanation with as much detail as
  98 possible.
  99
 100 ## Translations
 101
 102 The core translations of Luanti are performed using Weblate. You can access
 103 the project page with a list of current languages
 104 [here](https://hosted.weblate.org/projects/minetest/minetest/).
 105
 106 Builtin (the component which contains things like server messages, chat command
 107 descriptions, privilege descriptions) is translated separately; it needs to be
 108 translated by editing a `.tr` text file. See
 109 [Translation](https://dev.luanti.org/Translation) for more information.
 110
 111 ## Donations
 112
 113 If you'd like to monetarily support Luanti development, you can find donation
 114 methods on [our website](http://www.minetest.net/development/#donate).
 115
 116 # Maintaining
 117
 118 * This is a concise version of the
 119   [Rules & Guidelines](https://dev.luanti.org/engine-dev-process/) on the developer wiki.*
 120
 121 These notes are for those who have push access Luanti (core developers / maintainers).
 122
 123 - See the [project organisation](https://dev.luanti.org/Organisation) for the people involved.
 124
 125 ## Concept approvals and roadmaps
 126
 127 If a Pull Request is not a bug fix:
 128
 129 * If it matches a goal in [the roadmap](../doc/direction.md), then the PR should
 130   be labeled as "Roadmap" and the goal stated by number in the description.
 131 * If it doesn't match a goal, then it needs to receive a concept approval within
 132   a week of being opened to remain open. This 1 week deadline does not apply to
 133   PRs opened before the roadmap was adopted; instead, they may remain open or be
 134   closed as needed. Use the "Concept Approved" label. Issues can be marked as
 135   "Concept Approved" to give preapproval to future PRs.
 136
 137 ## Reviewing pull requests
 138
 139 Pull requests should be reviewed and, if appropriate, checked if they achieve
 140 their intended purpose. You can show that you are in the process of, or will
 141 review the pull request by commenting *"Looks good"* or something similar.
 142
 143 **If the pull-request is not [merge-able](#a-pull-request-is-considered-merge-able-when):**
 144
 145 Submit a comment explaining to the author what they need to change to make the
 146 pull-request merge-able.
 147
 148 - If the author comments or makes changes to the pull-request, it can be
 149   reviewed again.
 150 - If no response is made from the author within 1 month (when improvements are
 151   suggested or a question is asked), it can be closed.
 152
 153 **If the pull-request is [merge-able](#a-pull-request-is-considered-merge-able-when):**
 154
 155 Submit a :+1: (+1) or "Looks good" comment to show you believe the pull-request should be merged. "Looks good" comments often signify that the patch might require (more) testing.
 156
 157 - Two core developers must agree to the merge before it is carried out and both should +1 the pull request.
 158 - Who intends to merge the pull-request should follow the commit rules:
 159     - The title should follow the commit guidelines (title starts with a capital letter, present tense, descriptive).
 160     - Don't modify history older than 10 minutes.
 161     - Use rebase, not merge to get linear history:
 162     - `curl -Ls https://github.com/luanti-org/luanti/pull/1.patch | git am`
 163
 164 ## Reviewing issues and feature requests
 165
 166 - If an issue does not get a response from its author within 1 month (when requiring more details), it can be closed.
 167 - When an issue is a duplicate, refer to the first ones and close the later ones.
 168 - Tag issues with the appropriate [labels](https://github.com/luanti-org/luanti/labels) for devices, platforms etc.
 169
 170 ## Releasing a new version
 171
 172 *Refer to [dev.luanti.org/Releasing_Luanti](https://dev.luanti.org/Releasing_Luanti)*