Date: Mon, 23 Feb 2015 14:07:01 -0500 From: John Baldwin <jhb@freebsd.org> To: "Justin T. Gibbs" <gibbs@scsiguy.com> Cc: svn-src-stable@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org, svn-src-stable-9@freebsd.org, Garrett Cooper <ngie@freebsd.org> Subject: Re: svn commit: r278718 - in stable/9: etc/rc.d sbin share/man/man4 share/mk sys/modules/geom tools/build/mk tools/build/options Message-ID: <2645058.QN6AG2EogR@ralph.baldwin.cx> In-Reply-To: <B4417DBE-05D2-49ED-AD3F-F17913FF0467@scsiguy.com> References: <201502132136.t1DLaHLi008470@svn.freebsd.org> <5328252.MWfFGgsrnY@ralph.baldwin.cx> <B4417DBE-05D2-49ED-AD3F-F17913FF0467@scsiguy.com>
next in thread | previous in thread | raw e-mail | index | archive | help
On Monday, February 23, 2015 10:35:59 AM Justin T. Gibbs wrote: > On Feb 16, 2015, at 9:11 AM, John Baldwin <jhb@freebsd.org> wrote: >=20 > =E2=80=A6 >=20 > > On a more general note, if I'm merging a change with several follow= up > > fixes, I > =E2=80=A6 >=20 > > 2) I don't cut and paste all N logs verbatim. This tends to be ve= ry hard > > to read. > I used to feel this way too until I started to see the many varied wa= ys 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 tha= t > can=E2=80=99t easily pull in the original change text from all integr= ated > revisions, removing any content from the merge log is a problem. Eve= n 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. >=20 > Merges should also be made easier, not harder. It is one thing to re= quire > 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=E2=80=99t appropriate for the target of the merge). But to= require them > to be summarized just because the reader may have read the original c= hange > in another location just adds more work, both for the person doing th= e > merge and the future user of the revision data. I'm coming at this from a different angle I guess. When I was first us= ing=20 FreeBSD, I didn't read HEAD commits, but I did follow commits for 2.2-s= table. =20 What I cared about as a user of stable was what new features were comin= g into=20 2.2. I didn't really care about the details of the various bugfixes to= get=20 said feature into mature shape in HEAD that were bundled into a merge, = I just=20 cared about the new feature itself. That is, I'm assuming the reader _= hasn't_=20 already read this commit before, but that the extra noise makes it over= ly=20 verbose. I think these are only readable _if_ you've already read the = stream=20 of commits to HEAD prior so it is just a refresh of what's in your memo= ry vs=20 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 n= o idea really. Which could images does it support? How is it different from = what=20 was there before (was this the initial cloud image stuff, or did this j= ust add more, because I thought we shipped cloud images for 10.1 which pred= ates this)? I'm not trying to pick on Glen, but that log is basically a stream of=20= conciousness piece which might be great for psychoanalaysis, but it's n= ot very=20 accessible to someone wanting to know what changed. Here's another exa= mple: https://svnweb.freebsd.org/base?view=3Drevision&revision=3D189075 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 wer= e something like 50+, many of which were one-liner bug fix commit logs. = Had I=20 duplicated all the logs that commit message might have been hundreds of= lines=20 long, and very hard for a user to figure out what had actually changed = and why=20 it mattered. Here's a (shorter) and more recent example: https://svnweb.freebsd.org/base?view=3Drevision&revision=3D266339 This merges 20 commits that all contribute to implementing a single fea= ture,=20 and yet for someone reading stable/10 commits I believe it is clear wha= t this=20 one feature is. --=20 John Baldwin
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?2645058.QN6AG2EogR>