httpd-dev mailing list archives

Site index · List index
Message view « Date » · « Thread »
Top « Date » · « Thread »
From Jeff Trawick <traw...@gmail.com>
Subject Re: What goes in CHANGES and svn log comments?
Date Sat, 06 Feb 2010 14:19:18 GMT
On Sat, Feb 6, 2010 at 8:59 AM, Dan Poirier <poirier@pobox.com> wrote:
> Do we have any formal conventions (i.e. written down) on what kinds of
> changes require entries in CHANGES and what doesn't, and what
> information we include in CHANGES and svn log entries?

Here's a rough draft for people to throw stones at.

Often the text of the svn log and the CHANGES entry are the same, but
the distinct requirements sometimes result in different information.

svn log:

The svn log contains any information needed by
* fellow developers or other people researching source code changes/fixes
* end users (at least point out what the implications are for end
users; it doesn't have to be in the most user friendly wording)

The attribution for the change uses Submitted-by/Reviewed-by (or
implicit Submitted-by if it was submitted by the committer.)

(But I use different wording than "Reviewed-by" to reflect reviewing
plus corrections or extensions to the original fix.)

CHANGES

CHANGES is the subset of the information that end users need to see
when they upgrade from one release to the next:

* what can I now do that I couldn't do before
* what problems that we anticipate a user could have suffered from are now fixed

The usability of CHANGES for end users decreases as information of use
to few individuals, or which doesn't pertain to evaluating the new
release, is added.  Specifically:

* Fixes for bugs introduced after the last release don't belong in CHANGES.
* Fixes for bugs that we don't expect anybody noticed don't belong in
CHANGES.  (Bend the rule a little for outside contributions, as the
submitter may need to see their name in lights as reward for their
efforts, which typically were undertaken with no guarantee that any
committer would take interest.)
* Documentation fixes, whether for end users or developers, don't
belong in CHANGES.

The attribution for the change is anyone responsible for the code changes.


> The most logical place for something like that seems to be near the
> bottom of http://httpd.apache.org/dev/guidelines.html, but I'm not
> seeing anything there.

makes sense to me

Mime
View raw message