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

Submitted by:  Mohammad Akhlaghi <makhlaghi>
Submitted on:  Fri 27 May 2016 04:15:45 AM UTC  
 
Should Start On: Thu 26 May 2016 03:00:00 PM UTCShould be Finished on: Thu 26 May 2016 03:00:00 PM UTC
Category: DevelopmentPriority: 7 - High
Item Group: EnhancementStatus: None
Privacy: PublicPercent Complete: 0%
Assigned to: NoneOpen/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>
Project 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>
Project Administrator

 

No files currently attached

 

Depends on the following items: None found

Items that depend on this one: None found

 

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

    Do you think this task is very important?
    If so, you can click here to add your encouragement to it.
    This task has 0 encouragements so far.

    Only logged-in users can vote.

     

    Please enter the title of George Orwell's famous dystopian book (it's a date):

     

     

    No Changes Have Been Made to This Item

    Back to the top


    Powered by Savane 3.1-cleanup1