13.12.2 Commit guidelines ¶

To be able to cleanly integrate your work with the other developers, never commit on the master branch (see Production workflow for a complete discussion and Forking tutorial for a cookbook example). In short, leave master only for changes you fetch, or pull from the official repository (see Synchronizing).

In the Gnuastro commit messages, we strive to follow these standards. Note that in the early phases of Gnuastro’s development, we are experimenting and so if you notice earlier commits do not satisfy some of the guidelines below, it is because they predate that guideline.

Commit title

The commits have to start with one short descriptive title. The title is separated from the body with one blank line. Run git log to see some of the most recent commit messages as an example. In general, the title should satisfy the following conditions:

• It is best for the title to be short, about 60 (or even 50) characters. Most emulated command-line terminals are about 80 characters wide. However, we should also allow for the commit hashes which are printed in git log --oneline, and also branch names or the graph structure outputs of git log which are also commonly used.
• The title should not finish with any full-stops or periods (‘.’).

Commit body ¶

The body of the commit message is separated from the title by one empty line. Recall that anyone who has subscribed to gnuastro-commits mailing list will get the commit in their email after it has been pushed to master. People will also read them when they synchronize with the main Gnuastro repository (see Synchronizing). Finally, the commit messages will later be used to update the NEWS file on each release. Therefore the commit message body plays a very important role in the development of Gnuastro, so please adhere to the following guidelines.

• The body should be very descriptive. Start the commit message body by explaining what changes your commit makes from a user’s perspective (added, changed, or removed options, or arguments to programs or libraries, or modified algorithms, or new installation step, etc.).
• Try to explain the committed contents as best as you can. Recall that the readers of your commit message do not necessarily have your current background. After some time you will also forget the context, so this request is not just for others³¹⁰. Therefore be very descriptive and explain as much as possible: what the bug/task was, justify the way you fixed it and discuss other possible solutions that you might not have included. For the last item, it is best to discuss them thoroughly as comments in the appropriate section of the code, but only give a short summary in the commit message. Note that all added and removed source code lines will also be circulated in the gnuastro-commits mailing list.
• Like all other Gnuastro’s text files, the lines in the commit body should not be longer than 75 characters, see Coding conventions. This is to ensure that on standard terminal emulators (with 80 character width), the git log output can be cleanly displayed (note that the commit message is indented in the output of git log). If you use Emacs, Gnuastro’s .dir-locals.el file will ensure that your commits satisfy this condition (using M-q).
• When the commit is related to a task or a bug, please include the respective ID (in the format of bug/task #ID, note the space) in the commit message (from Gnuastro project webpage) for interested people to be able to followup the discussion that took place there. If the commit fixes a bug or finishes a task, the recommended way is to add a line after the body with ‘This fixes bug #ID.’, or ‘This finishes task #ID.’. Do not assume that the reader has internet access to check the bug’s full description when reading the commit message, so give a short introduction too.

Below you can see a good commit message example (do not forget to read it, it has tips for you). After reading this, please run git log on the master branch and read some of the recent commits for more realistic examples.

The first line should be the title of the commit

An empty line is necessary after the title so Git does not confuse
lines.  This top paragraph of the body of the commit usually describes
the reason this commit was done.  Therefore it usually starts with
"Until now ...".  It is very useful to explain the reason behind the
change, things that are not immediately obvious when looking into the
code.  You do not need to list the names of the files, or what lines
have been changed, do not forget that the code changes are fully stored
within Git :-).

In the second paragraph (or any later paragraph!) of the body, we
describe the solution and why (not "how"!) the particular solution was
implemented.  So we usually start this part of the commit body with
"With this commit ...".  Again, you do not need to go into the details
that can be seen from the 'git diff' command (like the file names that
have been changed or the code that has been implemented).  The important
thing here is the things that are not immediately obvious from looking
into the code.

You can continue the explanation and it is encouraged to be very
explicit about the "human factor" of the change as much as possible, not
technical details.