Split release notes by release branch

Review Request #3907 — Created May 19, 2016 and submitted

2639, 3468
benjyw, jsirois, lahosken, mateor, molsen, zundel

This review splits the release notes by release branch (ie, master for pre releases, 1.0.x for stable releases). This change is related-but-mostly-orthogonal-to https://rbcommons.com/s/twitter/r/3890/ , in that it uses all of the same terminology, but can land independently.

  • Split release notes by release branch, with a top-level link for each release.
  • Preserve the CHANGELOG.rst entry in order to act as a branching off point for per-branch notes.
  • Add a (pantsbuild/pants private) Subsystem to allow configuring the location of notes for each branch.
  • Fix the long_description fetching code in pants-plugins/src/python/internal_backend/utilities/register.py to fetch from the relevant notes file for the current version.

Deployed here: http://pantsbuild.github.io/staging/stuhood-release-notes-per-branch/index.html


  1. I don't think the 1.0.x should contain the entire history.

    In fact, maybe we should separate out the pre-1.0 changelog too so we have 3 disjoint sets of changelog entries:


    This is so that we don't have to keep a huge file, and would maybe allow us to post something sane when we publish to pypi.

    We could simply concatentate the changelogs together if you wanted to make a file that contained them all.

    1. Truncating 1.0.x definitely makes sense; will do that.

      The "before 1.0.0" items I'm less sure about. They're certainly in the same category as other pre releases, so would be easiest to keep them there.

      Regarding pypi: I think that's an orthogonal issue addressed by https://github.com/pantsbuild/pants/issues/1708 ... this review gets the "correct" history for the relevant release, but adds a TODO about slicing out the relevant snippet from the log.

    2. My thought on the pre-1.0 is that it keeps us from an ever growing monstrous changelog. Most folks probably don't care about changes fixed years ago. If we do want to publish a combined changelog we just concatenate the files and we get all the changes in a reasonable order

  1. Ship It!
    1. I feel this is better than before, although I'd still like to see pre-1.0 split off.

  1. Would you mind adding more details about the subsystem to the description?

  1. Ship It!
Review request changed

Status: Closed (submitted)

Change Summary:

Merged as 2e3449add3f6987704663072ac4a73e80c33e392 and published to http://www.pantsbuild.org/