Date: Mon, 23 Feb 2015 13:41:16 -0700 From: "Justin T. Gibbs" <gibbs@scsiguy.com> To: John Baldwin <jhb@freebsd.org> 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: <ED07D209-17A2-4321-8A05-474190E403F0@scsiguy.com> In-Reply-To: <2645058.QN6AG2EogR@ralph.baldwin.cx> References: <201502132136.t1DLaHLi008470@svn.freebsd.org> <5328252.MWfFGgsrnY@ralph.baldwin.cx> <B4417DBE-05D2-49ED-AD3F-F17913FF0467@scsiguy.com> <2645058.QN6AG2EogR@ralph.baldwin.cx>
next in thread | previous in thread | raw e-mail | index | archive | help
> On Feb 23, 2015, at 12:07 PM, John Baldwin <jhb@freebsd.org> wrote: >=20 > 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 = followup >>> fixes, I >> =E2=80=A6 >>=20 >>> 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=E2=80=99t 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. >>=20 >> 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=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 = change >> in another location just adds more work, both for the person doing = the >> merge and the future user of the revision data. >=20 > I'm coming at this from a different angle I guess. When I was first = using=20 > FreeBSD, I didn't read HEAD commits, but I did follow commits for = 2.2-stable. =20 > What I cared about as a user of stable was what new features were = coming 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 = overly=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 = memory vs=20 > 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). >=20 > https://svnweb.freebsd.org/changeset/base/277458 = <https://svnweb.freebsd.org/changeset/base/277458>; >=20 > Can you figure out what that change does in a 2 or 3 sentence summary? >=20 > I think it has something to do with building could images, but I have = no idea I at least got that it was about =E2=80=9Ccloud", not =E2=80=9Ccould=E2=80= =9D. :-) > 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 = just > add more, because I thought we shipped cloud images for 10.1 which = predates > this)? >=20 > 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 = not very=20 > accessible to someone wanting to know what changed. Apart from the need for a top-level summary, aren=E2=80=99t you really = complaining here about the content of the original commit messages? = That=E2=80=99s a different problem, which I agree we have at times. > Here's another example: >=20 > https://svnweb.freebsd.org/base?view=3Drevision&revision=3D189075 = <https://svnweb.freebsd.org/base?view=3Drevision&revision=3D189075>; >=20 > 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=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. A user who doesn=E2=80=99t 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: >=20 > https://svnweb.freebsd.org/base?view=3Drevision&revision=3D266339 = <https://svnweb.freebsd.org/base?view=3Drevision&revision=3D266339>; >=20 > This merges 20 commits that all contribute to implementing a single = feature,=20 > and yet for someone reading stable/10 commits I believe it is clear = what this=20 > one feature is. That=E2=80=99s 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=E2=80=99s a shame. =E2=80=94 Justin=
Want to link to this message? Use this URL: <https://mail-archive.FreeBSD.org/cgi/mid.cgi?ED07D209-17A2-4321-8A05-474190E403F0>