Merge pull request #3676 from GPCsolutions/contributing

Enhanced contributing guidelines

CONTRIBUTING.md

@@ -4,15 +4,14 @@ How to contribute to Dolibarr
 Bug reports and feature requests
 --------------------------------
 
-*Note*: Issues are not a support forum. If you need help using the software, please use [the forums](http://www.dolibarr.org/forum).
+<a name=not-a-support-forum></a>*Note*: Issues are not a support forum. If you need help using the software, please use [the forums](http://www.dolibarr.org/forum).
 
-**NEW**
+Issues are managed on [GitHub](https://github.com/Dolibarr/dolibarr/Issues).
-
-Issues are now managed on [GitHub](https://github.com/Dolibarr/dolibarr/Issues).
 
 1. Please [use the search engine](https://help.github.com/articles/searching-issues) to check if nobody's already reported your problem.
 2. [Create an issue](https://help.github.com/articles/creating-an-issue). Choose an appropriate title. Prepend appropriately with Bug or Feature Request.
-3. Report with as much detail as possible ([Use screenshots or even screencasts whenever possible](https://help.github.com/articles/issue-attachments)).
+4. Tell us the version you are using!
+3. Write a report with as much detail as possible (Use [screenshots](https://help.github.com/articles/issue-attachments) or even screencasts and provide logging and debugging informations whenever possible).
 
 We're still figuring out how to migrate old issues to GitHub. In the meantime, they are still available at [Doliforge](https://doliforge.org/projects/dolibarr).
 
@@ -41,9 +40,45 @@ Choose your base branch accordingly.
 ### General rules
 Please don't edit the ChangeLog file. A project manager will update it from your commit messages.
 
-### Commits
+### <a name=commits></a>Commits
 Use clear commit messages with the following structure:
 
+```
+[KEYWORD] [ISSUENUM] DESC
+
+LONGDESC
+```
+
+#### Keyword
+In uppercase to appear in ChangeLog when generated.
+
+The keyword can be ommitted if your commit does not fit in any of the following categories:
+- Fix: for a bug fix
+- Close: for closing a referenced feature request
+- New: for an unreferenced new feature (Opening a feature request and using close is prefered)
+
+#### Issuenum
+If your commit fixes a referenced bug or feature request.
+
+In the form of a # followed by the GitHub issue number.
+
+#### Desc
+A short description of the commit content.
+
+This should ideally be less than 50 characters.
+
+#### LongDesc
+A long description of the commit content.
+
+You can really go to town here and explain in depth what you've been doing.
+
+Feel free to express technical details, use cases or anything relevant to the current commit.
+
+This section can span multiple lines.
+
+Try to keep lines under 72 characters.
+
+#### Samples
 <pre>
 FIX|Fix #456 Short description (where #456 is number of bug fix, if it exists. In upper case to appear into ChangeLog)
 or
@@ -57,8 +92,10 @@ Long description (Can span accross multiple lines).
 </pre>
 
 ### Pull Requests
-When submitting a pull request, use same rule than Commits. With upper case keyword to appear into ChangeLog.
+When submitting a pull request, use same rule as [Commits](#commits) for the message.
 
+If your pull request only contains one commit, GitHub will be smart enough to fill it for you.
+Otherwise, please be a bit verbose about what you're providing.
 
 ### Resources
 [Developer documentation](http://wiki.dolibarr.org/index.php/Developer_documentation)
@@ -67,18 +104,18 @@ Translations
 ------------
 The source language (en_US) is maintained in the repository. See the [Code](#code) section above.
 
-All other translations are managed online at [Transifex](https://www.transifex.com/projects/p/dolibarr).
+All other translations are managed online at [Transifex](https://www.transifex.com/dolibarr-association/dolibarr/).
 
 Join an existing translation team or create your own and translate into the interface.
 
 Your translations will be available in the next major release.
 
 ### Resources
-[Translator documentation](http://wiki.dolibarr.org/index.php/Developer_documentation)
+[Translator documentation](http://wiki.dolibarr.org/index.php/Translator_documentation)
 
 Documentation
 -------------
 The project's documentation is maintained on the [Wiki](http://wiki.dolibarr.org/index.php).
 
-*You need to create an account before being able to edit.*
+*Note*: to help prevent spam, you need to create an account before being able to edit.