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 <i...@vucica.net> 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
