Skip to content

Commit

Permalink
Relax the CKAN commit guidelines
Browse files Browse the repository at this point in the history
No need to repeat a lot of stuff from the Pro Git Book about whitespace
and line lengths. Also make it clear that not every commit has to
reference a trac ticket.
  • Loading branch information
Sean Hammond committed Jun 15, 2012
1 parent 39943a7 commit f050a84
Showing 1 changed file with 10 additions and 15 deletions.
25 changes: 10 additions & 15 deletions doc/coding-standards.rst
Expand Up @@ -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
Expand All @@ -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:

::

Expand Down

0 comments on commit f050a84

Please sign in to comment.