You are viewing a plain text version of this content. The canonical link for it is here.
Posted to dev@httpd.apache.org by Dan Poirier <po...@pobox.com> on 2010/02/06 14:59:26 UTC
What goes in CHANGES and svn log comments?
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?
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.
If we don't have any documentation of our conventions, I'll volunteer to
write something (if there seems to be consensus on what the conventions
are).
Dan
Re: What goes in CHANGES and svn log comments?
Posted by Jeff Trawick <tr...@gmail.com>.
On Sat, Feb 6, 2010 at 10:36 AM, Dan Poirier <po...@pobox.com> wrote:
> Thanks Jeff. Some thoughts and questions for all:
>
> * I'd think that all security fixes should be mentioned in CHANGES, with
> CVE number, regardless of other considerations. Otherwise people
> worry.
absolutely; you could list the format of such entries in the guide
> * Should minor changes in the wording of a message be mentioned in
> CHANGES? I'd guess not, even though somebody just might be depending
> on that wording.
no; too few people care in general
> * I would think "Submitted-by" is required for all code provided by a
> non-committer, yes?
yes
>
> * Can we take it for granted that the person doing the commit has
> reviewed the code being committed that someone else contributed,
> or should we make a point of stating that explicitly in the log?
yes, this has been mentioned before
>
> * In trunk, does CHANGES document the changes from the last stable
> release, or from the previous alpha release of trunk? That would
> affect whether backported fixes should be mentioned in trunk CHANGES.
>
> * I think many changes to STATUS can get by with minimal log messages,
> e.g. "vote" or "propose backport".
or even
Keep rollin', rollin', rollin'
Though the streams are swollen,
Keep them dogies rollin', Rawhide!
Re: What goes in CHANGES and svn log comments?
Posted by "William A. Rowe Jr." <wr...@rowe-clan.net>.
On 2/17/2010 2:38 PM, Rainer Jung wrote:
> On 17.02.2010 20:45, Jeff Trawick wrote:
>> On Wed, Feb 17, 2010 at 2:38 PM, Dan Poirier<po...@pobox.com> wrote:
>>> On 2010-02-06 at 10:36, Dan Poirier<po...@pobox.com> wrote:
>>>
>>>> * In trunk, does CHANGES document the changes from the last stable
>>>> release, or from the previous alpha release of trunk? That would
>>>> affect whether backported fixes should be mentioned in trunk
>>>> CHANGES.
>>>
>>> Does anyone have comments on this question?
>>
>> An alpha is counted as a release, so upgraders from 2.3.6 alpha to
>> 2.3.7 alpha would expect to see what changed without looking at what
>> was backported to 2.2.x and delivered in both release streams.
>
> +1
/echo
Re: What goes in CHANGES and svn log comments?
Posted by Rainer Jung <ra...@kippdata.de>.
On 17.02.2010 20:45, Jeff Trawick wrote:
> On Wed, Feb 17, 2010 at 2:38 PM, Dan Poirier<po...@pobox.com> wrote:
>> On 2010-02-06 at 10:36, Dan Poirier<po...@pobox.com> wrote:
>>
>>> * In trunk, does CHANGES document the changes from the last stable
>>> release, or from the previous alpha release of trunk? That would
>>> affect whether backported fixes should be mentioned in trunk CHANGES.
>>
>> Does anyone have comments on this question?
>
> An alpha is counted as a release, so upgraders from 2.3.6 alpha to
> 2.3.7 alpha would expect to see what changed without looking at what
> was backported to 2.2.x and delivered in both release streams.
+1
Re: What goes in CHANGES and svn log comments?
Posted by Jeff Trawick <tr...@gmail.com>.
On Wed, Feb 17, 2010 at 2:38 PM, Dan Poirier <po...@pobox.com> wrote:
> On 2010-02-06 at 10:36, Dan Poirier <po...@pobox.com> wrote:
>
>> * In trunk, does CHANGES document the changes from the last stable
>> release, or from the previous alpha release of trunk? That would
>> affect whether backported fixes should be mentioned in trunk CHANGES.
>
> Does anyone have comments on this question?
An alpha is counted as a release, so upgraders from 2.3.6 alpha to
2.3.7 alpha would expect to see what changed without looking at what
was backported to 2.2.x and delivered in both release streams.
Re: What goes in CHANGES and svn log comments?
Posted by Dan Poirier <po...@pobox.com>.
On 2010-02-06 at 10:36, Dan Poirier <po...@pobox.com> wrote:
> * In trunk, does CHANGES document the changes from the last stable
> release, or from the previous alpha release of trunk? That would
> affect whether backported fixes should be mentioned in trunk CHANGES.
Does anyone have comments on this question?
Thanks,
Dan
Re: What goes in CHANGES and svn log comments?
Posted by Dan Poirier <po...@pobox.com>.
Thanks Jeff. Some thoughts and questions for all:
* I'd think that all security fixes should be mentioned in CHANGES, with
CVE number, regardless of other considerations. Otherwise people
worry.
* Should minor changes in the wording of a message be mentioned in
CHANGES? I'd guess not, even though somebody just might be depending
on that wording.
* I would think "Submitted-by" is required for all code provided by a
non-committer, yes?
* Can we take it for granted that the person doing the commit has
reviewed the code being committed that someone else contributed,
or should we make a point of stating that explicitly in the log?
* In trunk, does CHANGES document the changes from the last stable
release, or from the previous alpha release of trunk? That would
affect whether backported fixes should be mentioned in trunk CHANGES.
* I think many changes to STATUS can get by with minimal log messages,
e.g. "vote" or "propose backport".
Dan
Re: What goes in CHANGES and svn log comments?
Posted by Jeff Trawick <tr...@gmail.com>.
On Sat, Feb 6, 2010 at 8:59 AM, Dan Poirier <po...@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