Index: docs/DeveloperPolicy.rst =================================================================== --- docs/DeveloperPolicy.rst +++ docs/DeveloperPolicy.rst @@ -275,6 +275,40 @@ progress. The developer is welcome to re-commit the change after the problem has been fixed. +Commit message +-------------- + +Although we don't enforce the format of commit messages, there are general +guidelines that will help review, search in logs, email formatting and so on. +Mostly, the rules that apply are similar to other git repositories, such as: + +* Separate the commit message into title, body and the optional author. + +* The title should be concise. All commits are emailed to the list, and the + first line is used as the subject, so long titles are really frowned + upon. They also look a lot better in a `git log`. + +* The body, if it exists, should be separated from the title by an empty line. + +* The body should be aligned to 80 columns and have as many paragraphs as + necessary, but not more than that. Meaning you should be concise, but + explanatory, including a complete reasoning, but leaving examples, code + snippets and gory details to bug comments, web review or the mailing list. + +* `Attribution of Changes`_ should be in a separate line, after the end of + the body, as simple as "Patch by John Doe.". This is how we officially + handle attribution, and there are automated processes that use that, so + please keep this pattern. + +* Text formatting and spelling should follow the same rules as documentation + and in-code comments, ex. capitalization, full stop, etc. + +While these rules match most of the cases, we're aware that some cases are not +covered, and that's why we don't think reverting patches with "bad" commit +messages is a reasonable thing to do. We will, however, remind people of this +section of the policy for future reference. + + Obtaining Commit Access -----------------------