Re: on change logs (was: [BUG] man(7) page not showing footer)

[G. Branden Robinson]

Hi Alex,

At 2022-11-03T16:53:09+0100, Alejandro Colomar wrote:
> Ahh, I miss Michael so much for that!  Not having someone reviewing my
> patches allows me to commit such crimes.  Last month you can find a
> commit that reverted _the parent_ commit.  Just 15 minutes of
> difference.  I won't even link to it here, since it's a bit
> embarrasing :P

Minimal latency is not _always_ a blessing.  ;-)

> > I also suffix a commit message with asides, mentions of
> > miscellaneous or auxiliary changes (usually to the style of text
> > prose), or illustrative exhibits of formatter behavior before and/or
> > after the change.  This material I do _not_, as a rule, copy into
> > the commit message.
> 
> I couldn't parse the above.  I guess the last sentence wanted to say
> Changelog instead of commit message?

Yes, s/commit message\./ChangeLog entry./.  Yet another mistake.  :)

> > [...] a proper ChangeLog file has virtues.
> > 
> > 1.  It's available, or is required to made available on request, to
> >     all who receive the software.  This is explicit in GNU GPLv2,
> >     §2.
> > 
> >      "a) You must cause the modified files to carry prominent
> >      notices stating that you changed the files and the date of any
> >      change."
> > 
> 
> (1) is not really an issue, since saying "To learn more about changes
> applied to individual pages, use git(1)" already points to the changes
> list, so it's publicly available on request.

Would that it were so.  It has happened that certain vendors regard
their commit history to a GPLed source repository, even one in which
they are far from holding copyright in the contents, as a "value add",
and anyone apart from their staff, partners, and paying subscribers were
invited to just f*** off.

Quite an argument raged about this a while back.  Guys like me were not
on the winning side.

https://lwn.net/Articles/430098/
https://lwn.net/Articles/432012/

> This is fixed by reviewing changes.  However, let's admit it: no-one
> reviews my patches to the Linux man-pages, unless I consider it
> important enough to ask, and even then I often get no responses so I
> just push...

Many projects suffer from insufficient review.  I suspect this has
something do with it not being valued broadly across the software
engineering industry.  Code reviews aren't "real work".  While you can
find enlightened managers who don't share that view, business economics
still hasn't really recovered from the hangover of the Industrial
Revolution.  Entrepreneurs and Soviet commissars alike agreed that
"widgets per month" was the most valid productivity metric.  ("The only
thing that matters is this business is volume." -- Bill Gates)  Quality
assurance is a cost center, a thing to be minimized as aggressively as
possible.  Worse is better.

> I like to extend on commit messages, writing any details that may seem
> interesting, but often I make assumptions about what is "common
> knowledge" that may differ from what others consider common knowledge.
> And so I may write less clear than others would like.
> 
> However, by keeping a list of emails that one can reach in the commit
> log, if someone doesn't have those assumptions so clear can ask the
> commit authors and any other emails noted in the email.

Having lived through the destruction of DejaNews as a resource (by
Google, of course), and seen publicly available mailing list archives
flirt with death multiple times[1], I simply don't trust such resources
to survive.

> My main issue with changelogs is that they are not bound to any
> specific diff. For finding the related commit messages for a given
> code, it's as easy as running git-blame(1) and git-log(1) on a given
> file.  For finding the relevant entry in the changelog, that's
> speleology (since it's written in the same commit, it's not so hard,
> as git-blame(1) still works, but it's not so ideal).

That's true.  Nevertheless if a commit message is mistaken I appreciate
the possibility of a correction to the historical record being available
in an artifact that is coupled to the source distribution, not just
sitting in a "whoops" email in an archive that may or may not be
available, or may or may not have glitched and failed to archive the
message in question.

> I still have considerable doubts.  But yeah, I understand why you
> would want to edit changelogs, whhich you can't do with commit
> messages.

For a project that isn't groff, I might make a different choice.

> $ wc Changes.old
>   55425  181405 1627707 Changes.old
> 
> If this file is useful to anyone, I'd like to know how.  What kind of
> public uses that file?  I have never opened that file for anything
> useful.

I've grepped it several times, but I can't remember why for any of the
occasions.  Next time I find myself doing so, I'll see if I can report
my motivation to you.

> From your HACKING file, I could be interested in the NEWS file, if I
> was a casual user/packager, or in the git log, but I don't think I
> would be interested in reading the ChangeLog file.

Sometimes I forget to include a bug-closing annotation in a commit
message, or discover only in retrospect that a commit fixed a bug.
Here's a recent example.

https://lists.gnu.org/archive/html/groff-commit/2022-10/msg00233.html

I find duplicate bug reports really dispiritng (maybe that's just me),
so two-way discoverability (from bug tracker to source repository and
vice versa) is important to me.

Regards,
Branden

[1] https://lars.ingebrigtsen.no/2020/01/06/whatever-happened-to-news-gmane-org/

signature.asc
Description: PGP signature