Please can we write informative commit messages?

classic Classic list List threaded Threaded
3 messages Options
Reply | Threaded
Open this post in threaded view
|

Please can we write informative commit messages?

David Chisnall-7
Hello,

I realise that the GNUstep conventions recommend writing a ChangeLog entry rather than a sensible commit log, but this makes it quite painful to navigate the project history.  Tools like git blame and git log make it easy to see the history of a particular file or directory.  The GitHub web interface also provides convenient displays of these.  For example, if I want to see what the recent changes in NSLock.m were about, I can look at:

https://github.com/gnustep/libs-base/commits/master/Source/NSLock.m

If I found a bug, I can use this page to see who last touched the line of code and why:

https://github.com/gnustep/libs-base/blame/master/Source/NSLock.m

Having to find the ChangeLog entry that corresponds to a change is an unnecessary indirection.  Trying to go the other way is impossible - the changelog entries include only a date not a revision so if I want to see the diff associated with a ChangeLog entry the only way I can do so is by running git blame on the ChangeLog and finding the corresponding entry.

It is trivial to automatically generate a ChangeLog from a commit log, but decidedly nontrivial to do the reverse.

Looking at our recent commit messages, they’re almost all non-informative.  This creates a barrier for entry for new developers, because no one under the age of 40 would think to go and look in the ChangeLog to try to understand the motivation behind a change.

Please can we join the mid 1990s?

David


_______________________________________________
Gnustep-dev mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/gnustep-dev
Reply | Threaded
Open this post in threaded view
|

Re: Please can we write informative commit messages?

Fred Kiefer
I fully agree with you that we need more meaningful commit and ChangeLog messages. But if it is "trivial to automatically generate a ChangeLog from a commit log“ why did you fail to do so for your last commit? Could you please add this?

Fred

> Am 06.04.2018 um 11:52 schrieb David Chisnall <[hidden email]>:
>
> Hello,
>
> I realise that the GNUstep conventions recommend writing a ChangeLog entry rather than a sensible commit log, but this makes it quite painful to navigate the project history.  Tools like git blame and git log make it easy to see the history of a particular file or directory.  The GitHub web interface also provides convenient displays of these.  For example, if I want to see what the recent changes in NSLock.m were about, I can look at:
>
> https://github.com/gnustep/libs-base/commits/master/Source/NSLock.m
>
> If I found a bug, I can use this page to see who last touched the line of code and why:
>
> https://github.com/gnustep/libs-base/blame/master/Source/NSLock.m
>
> Having to find the ChangeLog entry that corresponds to a change is an unnecessary indirection.  Trying to go the other way is impossible - the changelog entries include only a date not a revision so if I want to see the diff associated with a ChangeLog entry the only way I can do so is by running git blame on the ChangeLog and finding the corresponding entry.
>
> It is trivial to automatically generate a ChangeLog from a commit log, but decidedly nontrivial to do the reverse.
>
> Looking at our recent commit messages, they’re almost all non-informative.  This creates a barrier for entry for new developers, because no one under the age of 40 would think to go and look in the ChangeLog to try to understand the motivation behind a change.
>
> Please can we join the mid 1990s?
>
> David


_______________________________________________
Gnustep-dev mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/gnustep-dev
Reply | Threaded
Open this post in threaded view
|

Re: Please can we write informative commit messages?

David Chisnall-7
On 6 Apr 2018, at 13:03, Fred Kiefer <[hidden email]> wrote:
>
> I fully agree with you that we need more meaningful commit and ChangeLog messages. But if it is "trivial to automatically generate a ChangeLog from a commit log“ why did you fail to do so for your last commit?

Because I have a finite amount of time to spend on GNUstep and don’t consider duplicating information in a less useful location to be a particularly productive use of that time.  It appears that the XSLT that I used with svn doesn’t work correctly with git and no one has bothered to update it because most projects moved away from ChangeLogs when they moved away from CVS (or, in some cases, when they moved away from RCS).

David


_______________________________________________
Gnustep-dev mailing list
[hidden email]
https://lists.gnu.org/mailman/listinfo/gnustep-dev