From owner-svn-src-stable-9@FreeBSD.ORG Mon Feb 23 20:41:24 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 70EB1B63; Mon, 23 Feb 2015 20:41:24 +0000 (UTC) Received: from aslan.scsiguy.com (www.scsiguy.com [70.89.174.89]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (Client did not present a certificate) by mx1.freebsd.org (Postfix) with ESMTPS id 3FD62BAF; Mon, 23 Feb 2015 20:41:23 +0000 (UTC) Received: from youathao-dell.sldomain.com (slboulder.spectralogic.com [192.30.190.3] (may be forged)) (authenticated bits=0) by aslan.scsiguy.com (8.14.9/8.14.9) with ESMTP id t1NKfLAt090312 (version=TLSv1/SSLv3 cipher=DHE-RSA-AES256-SHA bits=256 verify=NO); Mon, 23 Feb 2015 13:41:22 -0700 (MST) (envelope-from gibbs@scsiguy.com) Mime-Version: 1.0 (Mac OS X Mail 8.2 \(2070.6\)) 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 From: "Justin T. Gibbs" In-Reply-To: <2645058.QN6AG2EogR@ralph.baldwin.cx> Date: Mon, 23 Feb 2015 13:41:16 -0700 Message-Id: References: <201502132136.t1DLaHLi008470@svn.freebsd.org> <5328252.MWfFGgsrnY@ralph.baldwin.cx> <2645058.QN6AG2EogR@ralph.baldwin.cx> To: John Baldwin X-Mailer: Apple Mail (2.2070.6) Content-Type: text/plain; charset=utf-8 Content-Transfer-Encoding: quoted-printable X-Content-Filtered-By: Mailman/MimeDel 2.1.18-1 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 20:41:24 -0000 > On Feb 23, 2015, at 12:07 PM, John Baldwin 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 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 = >=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 = >=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 = >=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=