Everything which should not be said.

The case of Business Templates

Since Business Templates are issued from automatically-generated files, the developer's control on their content is limited. Things like indentation changes happen independently from developer will. Some of the following rules can't be strictly applied to Business Templates. Still, the developer must stick to them as much as possible, for example by committing separately his changes and file format changes (indentation, ...).

Moreover, some special rules apply only to Business Templates (see below).

Commits are purpose-based

A change in the code comes from a motivation : fix a bug, add a functionality, fix typos, add comments,... This purpose must be clearly stated in the changelog message, and it must actually be the purpose itself, not how it was implemented. This way, one provides others with a way to check that a given behavior in the modified code is desired or not.

Commits are atomic

Provided such motivation exist, all the modification made on the working copy needed to fulfill this motivation must be committed at the same time. This prevent the repository from being broken during a split commit.

Commits are concise

A commit must not fulfill multiple purposes at the same time. This is done to ease the tracking of a bug by bisection methods, since it helps keeping the patches (relatively) small and helps the reviewer to keep his mind focused on one feature when understanding the changes.

Case of white spaces

A subpart of this rule needs to be explicit : about white[spaces|lines].

Basically, if the purpose is not to remove/add an empty line, then the patch must not contain such change. Same goes for python-meaningless spaces. A separate commit must be done when fixing the coding style, especially in python where some extra spaces can cause bugs. Although I believe everyone reading this page has a decent python knowledge, it's better to be safe than sorry.

A special implication of this rule is to always have a blank line at the end of files, so that unified diff does not show a diff for the last line in some cases.


The code one commits will end up in multiple contexts :

Keep these "audiences" in mind when adding a log message :

Special rules for Business Templates

Always commit bt/revision

Since bt/revision is the only way to tell automatically whether the Business Template was modified and then deserves an update on a site, this file must be committed along with every change. Note that revision should always be increased.

Modify the right changelog

There are 2 changelog involved in business templates commits :

GuidelinesForBestCommitPractices (last edited 2011-07-18 12:42:47 by VincentPelletier)