svn commit: r278718 - in stable/9: etc/rc.d sbin share/man/man4 share/mk sys/modules/geom tools/build/mk tools/build/options

[Justin T. Gibbs]

> On Feb 23, 2015, at 12:07 PM, John Baldwin <jhb at freebsd.org> wrote:
> 
> On Monday, February 23, 2015 10:35:59 AM Justin T. Gibbs wrote:
>> On Feb 16, 2015, at 9:11 AM, John Baldwin <jhb at freebsd.org> wrote:
>> 
>> …
>> 
>>> On a more general note, if I'm merging a change with several followup
>>> fixes, I
>> …
>> 
>>> 2) I don't cut and paste all N logs verbatim.  This tends to be very hard
>>> to read.
>> I used to feel this way too until I started to see the many varied ways that
>> our downstream consumers import our revision history.  For folks who only
>> import a single branch at a time or use a revision control system that
>> can’t easily pull in the original change text from all integrated
>> revisions, removing any content from the merge log is a problem.  Even when
>> you do import all the data and have really good tools for parsing it, it is
>> nice when a naive search (a log of just the current branch) is enough for
>> you to find what you need.
>> 
>> Merges should also be made easier, not harder.  It is one thing to require
>> the change text to be edited to accurately reflect the content of the merge
>> (e.g. differences to maintain ABI compatibility, or the exclusion of hunks
>> that aren’t appropriate for the target of the merge).  But to require them
>> to be summarized just because the reader may have read the original change
>> in another location just adds more work, both for the person doing the
>> merge and the future user of the revision data.
> 
> I'm coming at this from a different angle I guess.  When I was first using 
> FreeBSD, I didn't read HEAD commits, but I did follow commits for 2.2-stable.  
> What I cared about as a user of stable was what new features were coming into 
> 2.2.  I didn't really care about the details of the various bugfixes to get 
> said feature into mature shape in HEAD that were bundled into a merge, I just 
> cared about the new feature itself.  That is, I'm assuming the reader _hasn't_ 
> already read this commit before, but that the extra noise makes it overly 
> verbose.  I think these are only readable _if_ you've already read the stream 
> of commits to HEAD prior so it is just a refresh of what's in your memory vs 
> something new.

That argues for a better executive summary at the top that allows a reader to quickly determine if the content below is interesting in the current context.  I have no issue with adding content, just with its removal.

> Let's take a different example (and this is on HEAD, not even stable).
> 
> https://svnweb.freebsd.org/changeset/base/277458 <https://svnweb.freebsd.org/changeset/base/277458>
> 
> Can you figure out what that change does in a 2 or 3 sentence summary?
> 
> I think it has something to do with building could images, but I have no idea

I at least got that it was about “cloud", not “could”. :-)

> really.  Which could images does it support?  How is it different from what 
> was there before (was this the initial cloud image stuff, or did this just
> add more, because I thought we shipped cloud images for 10.1 which predates
> this)?
> 
> I'm not trying to pick on Glen, but that log is basically a stream of 
> conciousness piece which might be great for psychoanalaysis, but it's not very 
> accessible to someone wanting to know what changed.

Apart from the need for a top-level summary, aren’t you really complaining here about the content of the original commit messages?  That’s a different problem, which I agree we have at times.

> Here's another example:
> 
> https://svnweb.freebsd.org/base?view=revision&revision=189075 <https://svnweb.freebsd.org/base?view=revision&revision=189075>
> 
> Sadly, this was my first "big" merge with SVN (was not at all feasible with
> CVS) and I did not list all the revisions.  Suffice it to say there were
> something like 50+, many of which were one-liner bug fix commit logs.  Had I 
> duplicated all the logs that commit message might have been hundreds of lines 
> long, and very hard for a user to figure out what had actually changed and why 
> it mattered.

A user who doesn’t know enough to understand the individual changes today, may need that information in the future.  For today, they just need enough information to quickly determine if, for their current purposes, the rest of the commit message can be ignored.

> Here's a (shorter) and more recent example:
> 
> https://svnweb.freebsd.org/base?view=revision&revision=266339 <https://svnweb.freebsd.org/base?view=revision&revision=266339>
> 
> This merges 20 commits that all contribute to implementing a single feature, 
> and yet for someone reading stable/10 commits I believe it is clear what this 
> one feature is.

That’s great if the goal of reading the commit message is to find out if the feature was merged.  What if, as a side effect, the commit also touched another area - an area you are trying to debug?  It may be possible to determine that a related file was modified, but the rational for why it was modified is now gone.  That’s a shame.

—
Justin