This is the mail archive of the libc-alpha@sourceware.org mailing list for the glibc project.


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]
Other format: [Raw text]

Re: ChangeLog entry complexity


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


Index Nav: [Date Index] [Subject Index] [Author Index] [Thread Index]
Message Nav: [Date Prev] [Date Next] [Thread Prev] [Thread Next]