Re: CHANGES.txt inconsistency

[Chris Nauroth <cn...@hortonworks.com>]

Hadoop utilizes a script from Yetus that generates release notes automatically by querying JIRA, in particular the optional Release Note field on each JIRA issue.

http://yetus.apache.org/documentation/0.3.0/releasedocmaker/

This doesn’t require additional maintenance of a CHANGES.txt file.

Now that I’ve performed the ZooKeeper release management process once, it appears to me that there currently is no real dependency on the CHANGES.txt file to provide any user-facing information.  We copy our release notes HTML out of JIRA’s view and paste it into our site docs during the release.  For patch attribution, revision control is authoritative, and I don’t think the choice of git vs. svn makes a difference as long as we are diligent about crediting the correct author in the commit message.

We’ve talked a bit before about trying to improve the build toolchain, with the general feeling that we should migrate to Maven first and then consider using Yetus for its new pre-commit capabilities.  However, I don’t think any of that needs to be a pre-requisite for dropping CHANGES.txt.

The one place where I see CHANGES.txt impacting a built deliverable is that we currently bundle it into the distribution tarball.  If we feel it important to have a file showing patch attribution within that tarball, then I suppose we need to keep it.  Personally, I think it’s OK to say source control is the system of record for that.

--Chris Nauroth

On 7/22/16, 8:49 PM, "Patrick Hunt" <ph...@apache.org> wrote:

    On Thu, Jul 21, 2016 at 3:59 PM, Chris Nauroth <cn...@hortonworks.com>
    wrote:
    
    > While working on the 3.5.2-alpha release, I noticed that CHANGES.txt in
    > trunk is not completely synchronized with the 3.5 release line.  In
    > branch-3.5, we have sections for releases 3.5.0, 3.5.1 and 3.5.2 (added by
    > me), each indicating their respective release dates.  In trunk, release
    > 3.5.0 is mentioned, but not release 3.5.1.  I have not yet added anything
    > about 3.5.2, because I wasn't sure if the omission of 3.5.1 was an
    > oversight or intentional.
    >
    > More generally, it appears that on any given branch, CHANGES.txt does not
    > comprehensively cover the prior major release lines.  On branch-3.5,
    > CHANGES.txt mentions release 3.4.0, release 3.3.0, etc., but not any of the
    > subsequent releases in those lines, like the recent 3.4.8.
    >
    > Is this something we need to correct?  Is it even worthwhile to keep
    > maintaining CHANGES.txt, or is it not worth the effort?  FWIW, other
    > projects like Hadoop and HBase have abandoned maintaining CHANGES.txt files
    > and instead rely on the revision log for patch attribution and various
    > forms of automation for generating release notes.
    >
    >
    It's been like that as far as I can remember. I don't see why we couldn't
    adopt the same approach as used by the other teams, if that makes the
    result better and our lives easier. It's a real pain, and very error prone,
    to try and keep the changes.txt up to date aside from the issues you
    mentioned as it's maintained "by hand" for each commit.
    
    What do hadoop/hbase do wrt to this information? Do we need to move to git
    (as these other teams have done) or can we do this with svn?
    
    Patrick