diff --git a/doc/coding-standards.rst b/doc/coding-standards.rst index 2fadde5bca7..770c6a8a631 100644 --- a/doc/coding-standards.rst +++ b/doc/coding-standards.rst @@ -7,22 +7,17 @@ Commit Guidelines Generally, follow the `commit guidelines from the Pro Git book`_: -- Avoid committing any whitespace errors. One tool you can use to find - whitespace errors is the ``git diff --check`` command. - - Try to make each commit a logically separate, digestible changeset. -- Try to make the first line of the commit message less than 50 characters - long, and describe the entire changeset concisely. +- The first line of the commit message should concisely summarise the + changeset. - Optionally, follow with a blank line and then a more detailed explanation of - the changeset, hard-wrapped to 72 characters, giving the motivation for the - change and contrasting the new with the previous behaviour. + the changeset. - Use the imperative present tense as if you were giving commands to the - codebase to change its behaviour, e.g. *Add tests for*, *make xyzzy do - frotz*, **not** *Adding tests for*, *I added tests for*, *[This patch] makes - xyzzy do frotz* or *[I] changed xyzzy to do frotz*. + codebase to change its behaviour, e.g. *Add tests for...*, *make xyzzy do + frotz...*, this helps to make the commit message easy to read. - Try to write the commit message so that a new CKAN developer could understand it, i.e. using plain English as far as possible, and not referring to too @@ -32,15 +27,15 @@ Generally, follow the `commit guidelines from the Pro Git book`_: .. _commit guidelines from the Pro Git book: http://git-scm.com/book/en/Distributed-Git-Contributing-to-a-Project#Commit-Guidelines In CKAN we also refer to `trac.ckan.org`_ ticket numbers in commit messages -wherever relevant. This makes the release manager's job much easier! There -should be few commits that don't refer to a trac ticket, e.g. if you find a -typo in a docstring and quickly fix it you wouldn't bother to create a ticket -for this. +wherever relevant. This makes the release manager's job much easier! Of +course, you don't have to reference a ticket from your commit message if there +isn't a ticket for it, e.g. if you find a typo in a docstring and quickly fix +it you wouldn't bother to create a ticket for this. Put the ticket number in square brackets (e.g. ``[#123]``) at the start of the first line of the commit message. You can also reference other Trac tickets elsewhere in your commit message by just using the ticket number on its own -(e.g. ``see #456``). Full example: +(e.g. ``see #456``). For example: ::