This is the mail archive of the
libc-alpha@sourceware.org
mailing list for the glibc project.
Re: ChangeLog entry complexity
- From: "Joseph S. Myers" <joseph at codesourcery dot com>
- To: Siddhesh Poyarekar <siddhesh dot poyarekar at gmail dot com>
- Cc: Eric Wong <normalperson at yhbt dot net>, Carlos O'Donell <carlos at redhat dot com>, Petr Baudis <pasky at ucw dot cz>, Roland McGrath <roland at hack dot frob dot com>, Ondřej Bílka <neleai at seznam dot cz>, <libc-alpha at sourceware dot org>
- Date: Wed, 27 Mar 2013 14:26:28 +0000
- Subject: Re: ChangeLog entry complexity
- References: <20130224085129 dot GA5898 at domone dot kolej dot mff dot cuni dot cz> <20130311132836 dot GA6016 at domone dot kolej dot mff dot cuni dot cz> <20130311162425 dot DAD282C083 at topped-with-meat dot com> <20130311174341 dot GA28265 at domone dot kolej dot mff dot cuni dot cz> <20130311174940 dot 0E0512C08D at topped-with-meat dot com> <513E4924 dot 4010500 at redhat dot com> <20130311214322 dot GC31274 at machine dot or dot cz> <20130311214635 dot 5B9D32C08F at topped-with-meat dot com> <20130325164624 dot GA6137 at machine dot or dot cz> <51508192 dot 90702 at redhat dot com> <20130325205300 dot GA24293 at dcvr dot yhbt dot net> <Pine dot LNX dot 4 dot 64 dot 1303261741360 dot 8202 at digraph dot polyomino dot org dot uk> <CAAHN_R34fC5CEy0E991QjsBd_7X9wOwdw1_OV+PiV-thi0E4Kg at mail dot gmail dot com>
On Wed, 27 Mar 2013, Siddhesh Poyarekar wrote:
> On 26 March 2013 23:25, Joseph S. Myers <joseph@codesourcery.com> wrote:
> > I think we *should* move to putting both title lines (as explicitly
> > described in the GNU Coding Standards) and rationale at the top of
> > ChangeLog entries, in addition to the descriptions of "what" changed, and
>
> A description of what changed is pointless IMO because that bit can be
> read from the patch itself. The 'why' is important and the commit log
> should be a good enough place for it.
No more pointless than any other table of contents, abstract, map or
executive summary - any of those could be determined from the thing
itself, but the guide is still useful for the reader. The things to
concentrate on in writing the "what" are describing changes at the human
level, in the order that makes the most sense to people (so consequential
updates of files after the substantive changes, for example).
Don't throw the baby out with the bathwater. ChangeLog entries provide a
useful level of description of changes, among other levels, and ensure
that source trees (exported into tarballs, whether releases or snapshots,
possibly imported elsewhere into other version control systems, etc.)
automatically carry information with them about what changes are present
in that particular source tree; distributions of (modified) source trees
without accompanying version control history are widespread, even if you
don't see them. It's in the cases where the level of information in the
ChangeLogs is disproportionately not useful - large global mechanical
changes (replacing a symbol with another, removing all uses of a macro,
fixing a particular formatting issue, etc.) - where we should consider
simplified entries such as just listing changed files along with a list of
the global changes applied, not details of which changes were applicable
to which files and which functions in those files, or for changes where
even the list of files is excessive entries of the form
* All files with FSF copyright notices: Update copyright dates
using scripts/update-copyrights.
rather than losing the useful content for most routine patches. Those
cases are also the same ones where the ChangeLog entries are a pain to
write. (For some large non-mechanical patches, the ChangeLog entries may
take a while to write but in those cases I think they are justified.)
> > also putting that detailed patch description in the commit messages. But
> > this would require that the detailed description be reviewed for
> > formatting and English usage in as much detail as the rest of the patch.
>
> The blurb accompanying a patch submission should usually be clear
> enough and wherever it is not, reviewers could make a note of it. I
> don't think a strict language review is necessary as long as what is
> written is clear enough.
The point is it's effectively becoming part of the documentation, to be
reviewed like other documentation (and if tools like gitlog-to-changelog
were to be used, it would be desirable to minimize the need to have
on-the-side list of amendments to past patch descriptions).
--
Joseph S. Myers
joseph@codesourcery.com