Format of the commit logs
If you are a relax developer and you have commit access to the repository the following conventions should be followed for all commit messages.
- The length of all lines in the commit log should never exceed 100 characters.
This is so that the log message viewed in either emails or by the command prompt command git log is legible.
In vim, for example, this can be set in the vimrc file with the line
- The first line of the commit log should be a short description or synopsis of the changes.
If the change relates to a bug or a task, include the bug and task number using the notation type #num where type is either bug, task or support and num is the id number (for example bug #6503).
Also include a link to the tracker.
- The second line should be blank.
- If the commit is a bug fix reported by a non-committer or if the commit originates from a patch posted by a non-committer the next lines should be reserved for crediting.
The name of the person and their obfuscated email address (for example edward _at_ nmr-relax _dot_ com) should be included in the message.
- Next should be another blank line.
- If the commit relates to an entry in the bug tracker or to a discussion on the mailing lists then the web address of either the bug report or the mailing list archive message should be cited in the next section (separated from the synopsis or credit section by a blank line).
All relevant links should be included to allow easy navigation between the repository, mailing lists, bug tracker, etc.
An example is the old bug #5559 which is now archived at https://web.archive.org/web/https://gna.org/bugs/?func=detailitem&item_id=5559
and the post to the relax development mailing list describing the fix to that bug which is archived at http://www.nmr-relax.com/mail.gna.org/public/relax-devel/2006-03/msg00013.html.
- A full description with all the details can follow.
This description should follow a blank line, can itself be sectioned using blank lines, and finally the log is terminated by one blank line at the end of the message.
Note these are old commit logs prior to the switch from SVN to git and prior to the Gna! shutdown (see Section 3.1 on page ).
An example of a commit message for the closure of a bug is:
Fixing the rest of bug #7241 (https://gna.org/bugs/?7241).
Bug #7241 was thought to be fixed in in r2591 and r2593, the commit messages describing the solution
being located at https://mail.gna.org/public/relax-commits/2006-09/msg00064.html (Message-id:
<E1GTgBi-0000R6email@example.com>) for r2591 and
<E1GTt6Cfirstname.lastname@example.org>) for r2593.
However this was not the only place that the Scientific Python PDB data structure peptide_chains was
being accessed. The chains were being accessed in the file 'generic_fns/sequence.py' when the
sequence was being read out of the PDB file. This has now been modified with changes similar to
r2591 and r2593.
An example of a commit message for changes relating to a task is:
This change implements half of task #3630 (https://gna.org/task/?3630).
The docstring in the generic optimisation function has been modified to clear up the ambiguity cased
by supplying the option 'None' together with Newton optimisation.
One last commit message example is:
Added the API documentation creation (using Epydoc) to the Scons scripts.
The Scons target to create the HTML API documentation is called 'api_manual_html'. The
documentation can be created by typing:
$ scons api_manual_html
The function 'compile_api_manual_html()' was added to the 'scons/manuals.py' file. This function
runs the 'epydoc' command. All the Epydoc options are specified in that function.
The relax user manual (PDF), created 2020-08-26.