[gnuastro-devel] [task #14008] Discussion on adopting ChangeLog format in commits

[Mohammad Akhlaghi]

URL:
  <http://savannah.gnu.org/task/?14008>

                 Summary: Discussion on adopting ChangeLog format in commits
                 Project: GNU Astronomy Utilities
            Submitted by: makhlaghi
            Submitted on: Fri 27 May 2016 01:15:45 PM JST
         Should Start On: Fri 27 May 2016 12:00:00 AM JST
   Should be Finished on: Fri 27 May 2016 12:00:00 AM JST
                Category: Development
                Priority: 7 - High
              Item Group: Enhancement
                  Status: None
                 Privacy: Public
        Percent Complete: 0%
             Assigned to: None
             Open/Closed: Open
         Discussion Lock: Any
                  Effort: 0.00

    _______________________________________________________

Details:

Since task #13779, we have dropped updating of the ChangeLog on each commit.
The ChangeLog can be generated automatically from the commit history at any
time (task #13779).

The ChangeLog format is defined to be very clear and informative providing a
fine-grained description of changes (in each file and functions within each
file, see the definition in the GNU Coding Standards:

https://www.gnu.org/prep/standards/html_node/Change-Logs.html

We might be able to adopt the ChangeLog format in the commit message body
guidelines. In this way, the tools that will automatically generate the
ChangeLog will also make a nicely formatted ChangeLog and the commit messages
and emails will also be very clear and fine-grained and in an itemized format.
Ofcourse, we will not just limit ourselves to changes, but additions can also
be listed.

This is particularly useful in the emails, in which the commit message is
followed by the changes in the code (basically 'git log -p'). A ChangeLog
formatted commit message would make inspecting the changes in the code much
more easier to follow: provinding the context for the change in each file as
part of the whole commit context.

Currently there is no particular formatting for the commit message, so the
developer will just explain the overall context of the commit, or changes in
the files together. 

One way this can be done in Emacs is as follows: After the work that is to be
committed is done, a diff of all the changes to be committed can be generated
(with 'C-x v D'), then by pressing enter on each change, you are taken to the
respective part of the code and by pressing 'C-x 4 a' the file and function
name will appear automatically in the ChangeLog with the correct formats,
ready for you to explain the change in that item. After all the changes are
documented in the ChangeLog format, the final log for that commit can be
copied into the commit message. 

Note that once task #14007 is complete, the ChangeLog will no longer be
version controlled, so it is up to each developer what they want to do with
the text remaining there in the proposed method above. We might even be able
to set Emacs settings to directly add the ChangeLog format (after pressing
'C-x 4 a') to the commit message instead of the ChangeLog file.

While adopting the ChangeLog format can be very easy for Emacs users, it can
be a little hard to do it manually for someone not using Emacs. I guess this
is the only drawback of this suggestion, but its advantages might outweight
the cost. 

If you have any suggestions on this issue, please share them here so we can
adopt the best strategy. For the time being, this task is just a discussion.




    _______________________________________________________

Reply to this item at:

  <http://savannah.gnu.org/task/?14008>

_______________________________________________
  Message sent via/by Savannah
  http://savannah.gnu.org/