[gnuastro-commits] master 9325aa0: Book: example of a good commit message added

[Mohammad Akhlaghi]

branch: master
commit 9325aa0d6c4a366d39b909bf68e40e526172e2df
Author: Mohammad Akhlaghi <mohammad@akhlaghi.org>
Commit: Mohammad Akhlaghi <mohammad@akhlaghi.org>

    Book: example of a good commit message added
    
    Until now the "Commit guidelines" section of the "Developing" chapter had
    just listed the suggestions and tips. But without a useful example it was
    hard for new users to adopt.
    
    With this commit, an example text has been added that actually describes
    the logic within each paragraph of the commit message to help clarify the
    ideal commit message to new developers.
---
 doc/gnuastro.texi | 30 +++++++++++++++++++++++++++++-
 1 file changed, 29 insertions(+), 1 deletion(-)

diff --git a/doc/gnuastro.texi b/doc/gnuastro.texi
index 913b274..8a86e72 100644
--- a/doc/gnuastro.texi
+++ b/doc/gnuastro.texi
@@ -30491,10 +30491,38 @@ the body with `@code{This fixes bug #ID.}', or 
`@code{This finishes task
 full description when reading the commit message, so give a short
 introduction too.
 @end itemize
-
 @end table
 
 
+Below you can see a good commit message example (don't forget to read it, it 
has tips for you).
+After reading this, please run @command{git log} on the @code{master} branch 
and read some of the recent commits for more realistic examples.
+
+@example
+The first line should be the title of the commit
+
+An empty line is necessary after the title so Git doesn't 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 aren't immediately obvious when looking into the
+code. You don't need to list the names of the files, or what lines
+have been changed, don't 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 don't 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 imprtant thing here is the things that aren't
+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.
+@end example
+
 
 @node Production workflow, Forking tutorial, Commit guidelines, Contributing 
to Gnuastro
 @subsection Production workflow