From owner-svn-src-stable-9@FreeBSD.ORG Mon Feb 23 21:04:04 2015 Return-Path: Delivered-To: svn-src-stable-9@freebsd.org Received: from mx1.freebsd.org (mx1.freebsd.org [IPv6:2001:1900:2254:206a::19:1]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by hub.freebsd.org (Postfix) with ESMTPS id D569F526; Mon, 23 Feb 2015 21:04:03 +0000 (UTC) Received: from bigwig.baldwin.cx (bigwig.baldwin.cx [IPv6:2001:470:1f11:75::1]) (using TLSv1 with cipher DHE-RSA-CAMELLIA256-SHA (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id A853AE74; Mon, 23 Feb 2015 21:04:03 +0000 (UTC) Received: from ralph.baldwin.cx (pool-173-54-116-245.nwrknj.fios.verizon.net [173.54.116.245]) by bigwig.baldwin.cx (Postfix) with ESMTPSA id 61BE4B939; Mon, 23 Feb 2015 16:04:02 -0500 (EST) From: John Baldwin To: "Justin T. Gibbs" 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 Date: Mon, 23 Feb 2015 16:03:44 -0500 Message-ID: <2219035.9lOfKPczSU@ralph.baldwin.cx> User-Agent: KMail/4.14.2 (FreeBSD/10.1-STABLE; KDE/4.14.2; amd64; ; ) In-Reply-To: References: <201502132136.t1DLaHLi008470@svn.freebsd.org> <2645058.QN6AG2EogR@ralph.baldwin.cx> MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Content-Type: text/plain; charset="utf-8" X-Greylist: Sender succeeded SMTP AUTH, not delayed by milter-greylist-4.2.7 (bigwig.baldwin.cx); Mon, 23 Feb 2015 16:04:02 -0500 (EST) Cc: svn-src-stable@freebsd.org, svn-src-all@freebsd.org, src-committers@freebsd.org, svn-src-stable-9@freebsd.org, Garrett Cooper X-BeenThere: svn-src-stable-9@freebsd.org X-Mailman-Version: 2.1.18-1 Precedence: list List-Id: SVN commit messages for only the 9-stable src tree List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Mon, 23 Feb 2015 21:04:04 -0000 On Monday, February 23, 2015 01:41:16 PM Justin T. Gibbs wrote: > > On Feb 23, 2015, at 12:07 PM, John Baldwin wrote:= > > I'm coming at this from a different angle I guess. When I was firs= t 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 fea= tures > > were coming into 2.2. I didn't really care about the details of th= e > > 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. T= hat > > is, I'm assuming the reader _hasn't_ already read this commit befor= e, but > > that the extra noise makes it overly verbose. I think these are on= ly > > readable _if_ you've already read the stream of commits to HEAD pri= or so > > it is just a refresh of what's in your memory vs something new. >=20 > That argues for a better executive summary at the top that allows a r= eader > to quickly determine if the content below is interesting in the curre= nt > context. I have no issue with adding content, just with its removal.= That's probably fair, but I think there are often short messages for co= mpile breakages are followups to bugs that don't really add value by being th= ere, and they aren't touching different code, they are a followup to the ori= ginal change. > > Let's take a different example (and this is on HEAD, not even stabl= e). > >=20 > > https://svnweb.freebsd.org/changeset/base/277458 > > > >=20 > > Can you figure out what that change does in a 2 or 3 sentence summa= ry? > >=20 > > I think it has something to do with building could images, but I ha= ve no > > idea > I at least got that it was about =E2=80=9Ccloud", not =E2=80=9Ccould=E2= =80=9D. :-) >=20 > > really. Which could images does it support? How is it different f= rom what > > was there before (was this the initial cloud image stuff, or did th= is just > > add more, because I thought we shipped cloud images for 10.1 which > > predates > > this)? Aside from the typo, it seems you don't have an answer to these questio= ns either? :) > > 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. >=20 > Apart from the need for a top-level summary, aren=E2=80=99t you reall= y complaining > here about the content of the original commit messages? That=E2=80=99= s a different > problem, which I agree we have at times. No, I've seen merges to stable that follow the same pattern. This just= happened to be a merge from a projects branch (instead of from HEAD to = stable) that I remembered well enough to look for. It's a general question of = how merge commits are logged though, whether from projects -> head or from head -> stable. Surely when I merge some feature from a p4 or git branch you don't want= me to dump the individual log messages (about 1/3 of which would be "Compile"= since I often run my editor on a separate machine from where I build/test the= changes) into the commit to head? > > Here's another example: > >=20 > > https://svnweb.freebsd.org/base?view=3Drevision&revision=3D189075 > > = > >=20 > > Sadly, this was my first "big" merge with SVN (was not at all feasi= ble > > 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 log= s. Had > > I duplicated all the logs that commit message might have been hundr= eds of > > lines long, and very hard for a user to figure out what had actuall= y > > changed and why it mattered. >=20 > A user who doesn=E2=80=99t know enough to understand the individual c= hanges today, > may need that information in the future. For today, they just need e= nough > information to quickly determine if, for their current purposes, the = rest > of the commit message can be ignored. So I do think that is an argument for having a summary unless you mean = that the way to quickly determine if a commit can be ignored is to just igno= re all merges. :) > > Here's a (shorter) and more recent example: > >=20 > > https://svnweb.freebsd.org/base?view=3Drevision&revision=3D266339 > > = > >=20 > > 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. >=20 > 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 touch= ed > another area - an area you are trying to debug? It may be possible t= o > determine that a related file was modified, but the rational for why = it was > modified is now gone. That=E2=80=99s a shame. I think if you are trimming the message, you don't trim notice of side effects. I do think you should still read the commit logs of all the c= hanges you are merging while composing the message. In the last commit above,= that log message actually highlights some of the larger changes by pulling l= ines from multiple of the listed commits into the summary. It is true that this requires time, and if folks feel that is a waste o= f time, so be it. OTOH, if the issue is that you don't trust folks to ed= it commit logs during a MFC, why do you trust them to write a commit log f= or a commit to HEAD? --=20 John Baldwin