Contributing.md: Various additions and edits (#7309)

Add a new point to encourage discussion before coding. Move the 'ask before significant coding' suggestion into this. Edit and extend commit message guidelines. Refer to core dev commit messages as good examples. Remove 'short' and 'briefly' from the description guideline to try to improve description quality. Larger text for '### A pull-request is considered ..'. Add a second roadmap link to celeron55's blog roadmap which is the 1st part of the forum roadmap. Add full stops to lists. Consistent text size for '## Donations'.
minetest · May 15, 2018 · 935f11a · 935f11a
1 parent 2f34797
commit 935f11a
Showing 1 changed file with 28 additions and 23 deletions.
diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
@@ -10,29 +10,34 @@ Contributions are welcome! Here's how you can help:
 
 ## Code
 
-If you are planning to start some significant coding, you would benefit from asking first on [our IRC channel](http://www.minetest.net/irc/) before starting.
-
 1. [Fork](https://help.github.com/articles/fork-a-repo/) the repository and [clone](https://help.github.com/articles/cloning-a-repository/) your fork.
 
-2. Start coding!
+2. Before you start coding, consider opening an [issue at Github](https://github.com/minetest/minetest/issues) to discuss the suitability and implementation of your intended contribution with the core developers. If you are planning to start some very significant coding, you would benefit from first discussing on our IRC development channel [#minetest-dev](http://www.minetest.net/irc/). Note that a proper IRC client is required to speak on this channel.
+
+3. Start coding!
     - Refer to the [Lua API](https://github.com/minetest/minetest/blob/master/doc/lua_api.txt), [Developer Wiki](http://dev.minetest.net/Main_Page) and other [documentation](https://github.com/minetest/minetest/tree/master/doc).
     - Follow the [C/C++](http://dev.minetest.net/Code_style_guidelines) and [Lua](http://dev.minetest.net/Lua_code_style_guidelines) code style guidelines.
     - Check your code works as expected and document any changes to the Lua API.
 
-3. Commit & [push](https://help.github.com/articles/pushing-to-a-remote/) your changes to a new branch (not `master`, one change per branch)
+4. Commit & [push](https://help.github.com/articles/pushing-to-a-remote/) your changes to a new branch (not `master`, one change per branch)
     - Commit messages should:
-        - Use the present tense
-        - Have a title which begins with a capital letter
-        - Be descriptive. (e.g. no `Update init.lua` or `Fix a problem`)
-        - Have a first line with less than *80 characters* and have a second line that is *empty*
-
-4. Once you are happy with your changes, submit a pull request.
-     - Open the [pull-request form](https://github.com/minetest/minetest/pull/new/master)
-     - Add a short description explaining briefly what you've done (or if it's a work-in-progress - what you need to do)
-
-##### A pull-request is considered merge-able when:
-
-1. It follows the [roadmap](https://forum.minetest.net/viewtopic.php?t=9177) in some way and fits the whole picture of the project.
+        - Use the present tense.
+        - Be descriptive. See the commit messages by core developers for examples.
+    - The first line should:
+        - Start with a capital letter.
+        - Be a compact summary of the commit.
+        - Preferably have less than 70 characters.
+        - Have no full stop at the end.
+    - The second line should be empty.
+    - The following lines should describe the commit, starting a new line for each point.
+
+5. Once you are happy with your changes, submit a pull request.
+     - Open the [pull-request form](https://github.com/minetest/minetest/pull/new/master).
+     - Add a description explaining what you've done (or if it's a work-in-progress - what you need to do).
+
+### A pull-request is considered merge-able when:
+
+1. It follows the roadmap in some way and fits the whole picture of the project: [roadmap introduction](http://c55.me/blog/?p=1491), [roadmap continued](https://forum.minetest.net/viewtopic.php?t=9177)
 2. It works.
 3. It follows the code style for [C/C++](http://dev.minetest.net/Code_style_guidelines) or [Lua](http://dev.minetest.net/Lua_code_style_guidelines).
 4. The code's interfaces are well designed, regardless of other aspects that might need more work in the future.
@@ -45,23 +50,23 @@ If you experience an issue, we would like to know the details - especially when
 1. Do a quick search on GitHub to check if the issue has already been reported.
 2. Is it an issue with the Minetest *engine*? If not, report it [elsewhere](http://www.minetest.net/development/#reporting-issues).
 3. [Open an issue](https://github.com/minetest/minetest/issues/new) and describe the issue you are having - you could include:
-     - Error logs (check the bottom of the `debug.txt` file)
-     - Screenshots
-     - Ways you have tried to solve the issue, and whether they worked or not
-     - Your Minetest version and the content (games, mods or texture packs) you have installed
-     - Your platform (e.g. Windows 10 or Ubuntu 15.04 x64)
+     - Error logs (check the bottom of the `debug.txt` file).
+     - Screenshots.
+     - Ways you have tried to solve the issue, and whether they worked or not.
+     - Your Minetest version and the content (games, mods or texture packs) you have installed.
+     - Your platform (e.g. Windows 10 or Ubuntu 15.04 x64).
 
 After reporting you should aim to answer questions or clarifications as this helps pinpoint the cause of the issue (if you don't do this your issue may be closed after 1 month).
 
 ## Feature requests
 
-Feature requests are welcome but take a moment to see if your idea follows the [roadmap](https://forum.minetest.net/viewtopic.php?t=9177) in some way and fits the whole picture of the project. You should provide a clear explanation with as much detail as possible.
+Feature requests are welcome but take a moment to see if your idea follows the roadmap in some way and fits the whole picture of the project: [roadmap introduction](http://c55.me/blog/?p=1491), [roadmap continued](https://forum.minetest.net/viewtopic.php?t=9177). You should provide a clear explanation with as much detail as possible.
 
 ## Translations
 
 Translations of Minetest are performed using Weblate. You can access the project page  with a list of current languages [here](https://hosted.weblate.org/projects/minetest/minetest/).
 
-### Donations
+## Donations
 
 If you'd like to monetarily support Minetest development, you can find donation methods on [our website](http://www.minetest.net/development/#donate).