taskGNU Astronomy Utilities - Tasks: task #14008, Discussion on adopting ChangeLog...

 
 

You are not allowed to post comments on this tracker with your current authentication level.

task #14008: Discussion on adopting ChangeLog format in commits

Submitter:  Mohammad Akhlaghi <makhlaghi>
Submitted:  Fri 27 May 2016 04:15:45 AM UTC
   
 
Should Start On:  Thu 26 May 2016 03:00:00 PM UTC Should be Finished on:  Thu 26 May 2016 03:00:00 PM UTC
Category:  Development Priority:  7 - High
Item Group:  Enhancement Status:  None
Privacy:  Public Assigned to:  None
Percent Complete:  0% Open/Closed:  Open
Effort:  0.00

Sun 29 May 2016 05:12:40 PM UTC, comment #1: 

In addition to the strategy you described, it's worth noting that using a ChangeLog-like commit style is even easier when using Magit.

Anyway, doing this manually with any editor other than Emacs is a mess at best.  While I'm a happy Emacs user, I'm contrary to force all contributors to use it.

My position is still the same I expressed here: https://lists.gnu.org/archive/html/gnuastro-devel/2016-05/msg00019.html  Putting too many uncommon rules on contributors is likely to keep them away rather than attracting them.

Mosè Giordano <giordano>
Group Member
Fri 27 May 2016 04:15:45 AM UTC, original submission:  

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.

Mohammad Akhlaghi <makhlaghi>
Group administrator

 

(Note: upload size limit is set to 16384 kB, after insertion of the required escape characters.)

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

Carbon-Copy List
  • -email is unavailable- added by giordano (Posted a comment)
  • -email is unavailable- added by makhlaghi (Submitted the item)
  •  

    There are 0 votes so far. Votes easily highlight which items people would like to see resolved in priority, independently of the priority of the item set by tracker managers.

     

    No changes have been made to this item

    Back to the top

    Powered by Savane 3.13-f8d8.
    Corresponding source code