gnustep-dev
[Top][All Lists]
Advanced

[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]

Re: Changelog and git log hygiene


From: Ivan Vučica
Subject: Re: Changelog and git log hygiene
Date: Mon, 6 Apr 2020 14:57:06 +0100

I can concur it can be senseless with 1:1 mapping between commits and the logs.

However neither is that true, not have the git commit messages been kept up to date, nor has there been an easily interpretable log of what changes have been made.

I would propose changelog can be mutable (if you keep working on a change, update it over time). Or we can keep a differently formed log of changes. Git messages are inappropriate, in my opinion, because they are about tracking individual chunks of changes ("tactics"), not the larger change ("strategy"). Think: "there should be a cover message for commits", as is the case with mailing list based review and merge approach. Pull request model is a possible way out, but requires everyone to consistently adopt it; the message ends up in there as a merge commit, editable at the time of the merge, which is nice.



But either there's more sensible logging of changes over time, or we do away with announcing changes in a release that happens yearly. Because as is, it's too much for a person to spend an afternoon being effectively a journalist of code archaeology. 

Is this a fix? Is this a security fix? Is this just a part of a security fix? Or is this a new feature? Or is this a portion of a new feature? Has this skeleton implementation been finished before this release -- how do we announce the work done? "Implemented" or "stubbed out"?



Either everyone please agree to keep a journal in ChangeLog file, or another change log; or consistently write about large chunks of code you wrote (e.g. NSOrderedSet as one entry of 3 sentences rather than 30 commits without anything related among them) so we can put them in release notes.

But whoever is cutting the next release (likely me, I'm ok doing it) should not have to understand and sift through one sentence commits that describe what was done, but neither why nor on what. Treat git commits as isolated, or treat merge commits as a unit of work, or write some descriptive log, or elect not to announce changes.

Those are the options.

sent from phone

On Mon, Apr 6, 2020, 14:37 Gregory Casamento <address@hidden> wrote:
I, honestly, believe that the ChangeLog should be phased out.  Either that, or the git log should be used to generate it.   I, need to update the ChangeLog as I have not added a LOT of my recent changes since they have been extensive.   I realize I am in the wrong here, but I can see the logic in David C's previous assertion that the ChangeLog should be done away with.   Just my thoughts.

GC

On Sun, Apr 5, 2020 at 11:51 AM Ivan Vučica <address@hidden> wrote:
Hello!

For sake of making future releases easier, can we please:

- keep ChangeLog up to date
- ensure ChangeLog content is in vague sync with commit messages (not
exact, as it would defeat the purpose, but at least approximate)
- make sure our commit messages are cleaner


Examples with minor edits for formatting follow. Note that this looks
to be a problem across the board with all committers, nobody in
particular:

====
git commit message:
"Fix crash in gdomap when an invalid hostname is given for the -M option"
changelog message:
"* Tools/domap.c:
Fix crash in donames() when getaddrinfo returns an error"

I find the first one much more useful for a newsfile; but the second
one is useful implementation detail. I would argue both should be in
both changelog and commit message. But this is still fine and
understandable.

====
git commit messages:
"Fix wrong \U sequence for leter `i` and short weekdays."
"Update ChangeLog for last commit to Ukrainian language."
"Merge pull request #35 from trunkmaster/master: Updates for Ukrainian language"
changelog message:
"* Resources/Lanuages/Ukrainian:
Fix wrong \U sequence for letter 'i' and short weekdays."

Knowing in commit message that the change was done to the Ukrainian
language would be useful. Sure, I can pass --stat to git log -r
${PREVRELEASE}..master --reverse, but a clearer message (especially
the first line, the one usually up to 70ch) would be better.

Especially since --stat actually makes the whole log way harder to read.

====
git commit message:
"Correct implementation of method."
"Correct method names."
changelog message:
nothing on April 9, but there is a more detailed message on April 12
-- presumably this is because this is a merged larger chain of
messages?

This is generally fine if I could be sure ChangeLog is reliable and
consistently up to date. I'm reviewing logs as I am actually not sure
this is the case. Then, a message that says "fixed method" and nothing
else isn't helpful. File changed is Source/NSString.m, so I suspect
the longer message about character sets actually applies, but still...



Clearly I can and will be happy to release as-is and I will try to
keep release notes useful to anyone that may want to peek at them.
However, continued vigilance *when* making a commit -- it means not
only people stay up to date *at the time of making a commit*, but also
helps whomever happens to be cutting the release 15 months later.

Please, write the commit messages as if people view the commits
standalone. Please, write them as if someone is reading through them
without context over a year later.


Am I myself writing commit messages and changelog entries right? No
idea; I can only share with you the experience while cutting a
release. For entertainment purposes, take 1-2min and try to consider
how you'd write release notes from the output of this:

PREVRELEASE=$(git describe --abbrev=0) # should be: base-1_26_0
git log -r ${PREVRELEASE}..master --reverse
git diff -r ${PREVRELEASE}..master ChangeLog

:-)



--
Gregory Casamento
GNUstep Lead Developer / OLC, Principal Consultant
http://www.gnustep.org - http://heronsperch.blogspot.com
https://www.patreon.com/bePatron?u=352392 - Become a Patron

reply via email to

[Prev in Thread] Current Thread [Next in Thread]