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

[John Baldwin]

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.

Let's take a different example (and this is on HEAD, not even stable).

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
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.  Here's another example:

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.

Here's a (shorter) and more recent example:

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.

-- 
John Baldwin