-
Re: Dropping CHANGES.txt?Matt Foley 2011-11-21, 19:49
Hi Todd,
As you know, one of the tasks of a release manager is to gather a correct
and complete statement of all changes in a release, and include them in the
Release Notes. As I've done the release management for 0.20-security, I've
had the fun of seeing all the deficiencies of both CHANGES.txt and Jira,
for this purpose.
I recommend keeping CHANGES.txt. While it is nominally redundant, it
provides a valuable check-and-balance to the deficiencies of Jira and SVN
for this purpose. Here are the problems:
1. People make mistakes in Jira. With old bugs, they may mark something
resolved while the "Fixed in" field includes a
wished-for-but-not-actually-fixed release number. Even with new bugs where
the "Target" field should prevent this, I've found bugs marked resolved,
that are stated to be fixed in a given version but aren't actually.
2. People make mistakes in SVN commit messages. If they neglect to include
a bug number, then no commit shows in the Jira, and it can be really hard
to figure out if a given patch was actually applied to a given branch, by
examining either the Jira or the SVN logs.
3. People committing merges often don't include the bug number in the
commit message, especially if it is a composite merge of multiple changes.
Again, this means it is very difficult to determine if a given patch was
actually applied to a given branch, by examining either the Jira or the SVN
logs.
The advantage of CHANGES.txt is that it merges when the branch merges. So
as long as the developers stick to reasonably normal merge and commit
processes, it truly reflects what is in the current state of any given
branch, at least at the level of changes related to Jiras.
Of course, this is also circumvented by human errors. But it's pretty
valuable anyway.
--Matt
On Mon, Nov 21, 2011 at 11:01 AM, Todd Lipcon <[EMAIL PROTECTED]> wrote:
> I was thinking... our use of CHANGES.txt is a bit silly - we basically
> maintain all of our changes in three places (a) JIRA fixVersion field,
> (b) CHANGES.txt, and (c) the SVN changelog. It seems to me that we get
> very little value out of CHANGES.txt -- the contents are way too large
> (and terse) for any user to really follow, and it doesn't show us much
> that JIRA wouldn't.
>
> Two possible proposals for discussion:
>
> Proposal 1) Completely remove CHANGES.txt. Part of the release job
> would be to export the list of fixed JIRAs into an HTML file which we
> can ship with the release.
>
> With this proposal I'd also consider adding a checkbox to JIRA for
> "Include in changelist?" Anything with an explicit release note or the
> "Include in changelist" checkbox would get published.
>
> Proposal 2) Leave CHANGES.txt, but make it more of a value judgment on
> the part of the committer/patch author whether a patch deserves to go
> in there. The main criteria would be "would a user care?" For example,
> if it's a bug fix for something that regressed in SVN but was never
> released, the user wouldn't care. If it's a bug fix from a previous
> release, they would. If it's a minor build change or a fix to a unit
> test, they wouldn't. etc etc (we could write up some guidelines on the
> wiki)
>
> Any support for the above?
> -Todd
> --
> Todd Lipcon
> Software Engineer, Cloudera
>
As you know, one of the tasks of a release manager is to gather a correct
and complete statement of all changes in a release, and include them in the
Release Notes. As I've done the release management for 0.20-security, I've
had the fun of seeing all the deficiencies of both CHANGES.txt and Jira,
for this purpose.
I recommend keeping CHANGES.txt. While it is nominally redundant, it
provides a valuable check-and-balance to the deficiencies of Jira and SVN
for this purpose. Here are the problems:
1. People make mistakes in Jira. With old bugs, they may mark something
resolved while the "Fixed in" field includes a
wished-for-but-not-actually-fixed release number. Even with new bugs where
the "Target" field should prevent this, I've found bugs marked resolved,
that are stated to be fixed in a given version but aren't actually.
2. People make mistakes in SVN commit messages. If they neglect to include
a bug number, then no commit shows in the Jira, and it can be really hard
to figure out if a given patch was actually applied to a given branch, by
examining either the Jira or the SVN logs.
3. People committing merges often don't include the bug number in the
commit message, especially if it is a composite merge of multiple changes.
Again, this means it is very difficult to determine if a given patch was
actually applied to a given branch, by examining either the Jira or the SVN
logs.
The advantage of CHANGES.txt is that it merges when the branch merges. So
as long as the developers stick to reasonably normal merge and commit
processes, it truly reflects what is in the current state of any given
branch, at least at the level of changes related to Jiras.
Of course, this is also circumvented by human errors. But it's pretty
valuable anyway.
--Matt
On Mon, Nov 21, 2011 at 11:01 AM, Todd Lipcon <[EMAIL PROTECTED]> wrote:
> I was thinking... our use of CHANGES.txt is a bit silly - we basically
> maintain all of our changes in three places (a) JIRA fixVersion field,
> (b) CHANGES.txt, and (c) the SVN changelog. It seems to me that we get
> very little value out of CHANGES.txt -- the contents are way too large
> (and terse) for any user to really follow, and it doesn't show us much
> that JIRA wouldn't.
>
> Two possible proposals for discussion:
>
> Proposal 1) Completely remove CHANGES.txt. Part of the release job
> would be to export the list of fixed JIRAs into an HTML file which we
> can ship with the release.
>
> With this proposal I'd also consider adding a checkbox to JIRA for
> "Include in changelist?" Anything with an explicit release note or the
> "Include in changelist" checkbox would get published.
>
> Proposal 2) Leave CHANGES.txt, but make it more of a value judgment on
> the part of the committer/patch author whether a patch deserves to go
> in there. The main criteria would be "would a user care?" For example,
> if it's a bug fix for something that regressed in SVN but was never
> released, the user wouldn't care. If it's a bug fix from a previous
> release, they would. If it's a minor build change or a fix to a unit
> test, they wouldn't. etc etc (we could write up some guidelines on the
> wiki)
>
> Any support for the above?
> -Todd
> --
> Todd Lipcon
> Software Engineer, Cloudera
>
