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

[Alejandro Colomar]

Hi Branden,

On 11/3/22 03:18, G. Branden Robinson wrote:
> > I'll get it from git soon.  I'm not in a hurry for it ;)
>
> A good thing too.  Incidentally this is one reason I don't push every
> day even though I work on groff almost every day.  After 24-72 hours I
> often realize that some change I have made is boneheaded, and I revise
> it or back it out.

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

> > I wonder why so much duplication.  The ChangeLog seems like an exact
> > _duplicate_ of the git history.
>
> It's a subset.  I am continuing the practice that I was trained on when
> I joined groff development.  It wasn't written down anywhere except
> emails, though.  I've since added a HACKING file and documented it.
>
> https://git.savannah.gnu.org/cgit/groff.git/tree/HACKING
>
> 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?

> > I chopped the Linux man-pages 'Changes' file considerably by having a
> > high level overview of the changes, and deferring to git(1) for
> > further details.
>
> There are some groff contributors who are vocally opposed to the
> practice.  After some initial frustration with it, while I found a
> workflow that suited me (and discovering that Werner is a reliable
> source of good advice), I have come to see it as useful.  Setting aside
> the stuff that is documented _only_ in commit messages (documentation
> tweaks, cosmetic code changes), 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."
>
>      This provision dated to a time when change logs were maintained on a
>      per-file basis, usually in a whopping big comment block at the top
>      of the file.  A GNU-style ChangeLog file honors the spirit of the
>      foregoing provision.  I seem to remember that during the GPLv3
>      drafting process, this requirement was uncontroversially revised to
>      reflect common practice even in GNU projects and the supersession of
>      file-based revision control systems (SCCS, RCS) by hierarchical ones
>      ("repositories").
>
>      I can't find the updated language in GPLv3 at a quick glance, but I
>      don't regard that as determinative; the GNU GPL was written to
>      codify and promote good _social_ practices of software sharing.
>      We've had 25 years to observe the results when people hew to them
>      only grudgingly.  Ideally, people who hate copyleft would stick to
>      their BSD and MIT licenses while chasing their dreams of mixing a
>      little secret, proprietary sauce into free code and thereby living
>      out their days on a yacht sustained by the glorious extraction of
>      monopoly rents.  Of course that is a utopian perspective; the modus
>      operandum of a rentier is to find new and vibrant social contracts
>      to join and defect from in swift succession, maximizing gains.  If a
>      community doesn't survive such predation, those defectors who have
>      read a little Schumpeter (perhaps at Nth hand) will characterize
>      their actions as "creative destruction".

(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.  Having it in the tarball itself is just a 
convenience to those who inspect tarballs, which these days is not as common as 
it once was, I like to think.

> 2.  It's mutable; commit messages are not, but people make mistakes.  I
>      make mistakes all the time.  Typos and even occasional errors of
>      fact get into my commit messages, and moreso because, unlike some, I
>      am not committed to terseness above all other virtues.  It is easy
>      to write a useless commit message, and easier still to tell oneself
>      that one is thereby upholding the elegant traditions of Unix and C.

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...

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.

>      If we restrict the legitimate purpose of a ChangeLog entry or commit
>      message only to the "what" of a change set, then you don't need it:
>      a diff suffices to tell you _what_ changes were made.  Commit
>      messages, like code comments, should be concerned with "what"
>      insofar as doing so enables clear expression of the more important
>      matter of _why_ changes were made.  I try to explain the changes I
>      make, both so I can defend myself in the arguments that occasionally
>      arise in software development, and more fundamentally so that I can
>      later _remember_ why I made them.
>
>      Human brains can be slick surfaces.  I often find I have to modify
>      an old ChangeLog entry (usually one of my own) to clarify or correct
>      it, usually to explain what _really_ changed or what _actual_ facts
>      obtained at the time, instead of the ones I deludedly believed at
>      the time I first wrote it.

I admit having wanted to rebase some times to ammend a commit message.  Not so 
often though, for a reason:  normally, when the commit message is not so good, 
the diff itself was also not so good, so I find an excuse to make some little 
change in the code, and then I can add whatever commit message I think was deserved.

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).

>      I will note that I generally don't _retrospectively_ revise others'
>      ChangeLog entries.  (I may help compose them as part of an initial
>      commit.)  If I find commentary is essential for honest communication
>      with the users, I tend to put it in brackets and sign it with my
>      initials.
>
> I hope this sheds some light on things.  I know you asked for it earlier
> and I didn't have the wherewithal to write all this down at the time.

No problem! :)

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

> Other projects don't necessarily need to follow the same practices; the
> foregoing is my defense of existing practice in groff, which has the
> virtue of long continuity.
>
> I can say I'm very much looking forward to retiring the current
> ChangeLog file to ChangeLog.123.  Its length could be considered
> embarrassing. 😅

Heh, in the man-pages we only have one Changes.old:

$ 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.

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.

Thanks!

Alex

> Regards,
> Branden

--
<http://www.alejandro-colomar.es/>

OpenPGP_signature
Description: OpenPGP digital signature