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.
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:
git log --oneline, and also branch names or the graph structure outputs of
git logwhich are also commonly used.
The body of the commit message is separated from the title by one empty
line. Recall that anyone who has subscribed to
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.
git logoutput 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).
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.