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 <greg.casame...@gmail.com>
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 <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
>
