Adopt towncrier for the changelog

[bhrutledge]

Closes #546, based on consensus in #546 (comment).

I started by researching projects that use towncrier to find patterns and prior art; my notes are at https://gist.github.com/bhrutledge/e24ec851424f23634e250dbcfa59f45d.

Changes

• Add tox -e changelog to run towncrier
• Add changelog/ fragments for 3.2.0...master
• Add changelog.rst as a preview of the result

TODO

• Settle on on file structure, fragment types, and formatting
  • Currently using default fragments: feature, bugfix, doc, removal, misc
  • Currently using default template
• Incorporate into existing docs/changelog.rst
  • First attempts (i.e. living alongside releases format) caused docs build to fail
  • Remove existing releases tooling
  • Reformat existing changelog entries
• Document use of SemVer at top of changelog.rst
• Add changelog entry
• Remove example changelog entry
• Add contributing docs
• Add to Twine release process

Maybe/Later:

• Add .github/PULL_REQUEST_TEMPLATE.md to ask for (among other things) a changelog entry
• Show unreleased/"draft" fragments at top of changelog.rst

[sigmavirus24]

Looks good so far

[jaraco]

Looks good to me. Thanks for investing in this.

As for naming, setuptools uses the name finalize as the action to render the changelog. Maybe consider that for consistency.

• Settle on file structure, fragment types, and formatting

  • Currently using default fragments: feature, bugfix, doc, removal, misc
  • Currently using default template

I like your instincts on sticking with defaults. I avoid deviating from defaults unless there's a compelling reason (and not just a preference).

* [ ]  Incorporate into existing `docs/changelog.rst`
  
  * First attempts (i.e. living alongside `releases` format) caused `docs` build to fail
  * This probably requires removing the existing `releases` tooling
  * It doesn't seem too painful to reformat the existing changelog entries

Removing releases tooling sounds not so great. One option might be to take the existing changelog and tuck it away as a legacy changelog, but present both together in some form that renders each separately. Also saves the trouble of reformatting. But honestly, I'm a little surprised that the existing changelog couldn't be readily molded to fit the town crier design. I believe Setuptools was able to maintain a continuous changelog even as transitioning to towncrier.

* [ ]  Document use of SemVer at top of `changelog.rst`

I'm -0 on this, especially if it adds toil to the release process. If it's straightforward or can be made so (such as by putting the declaration elsewhere in the docs, even above where the changelog is rendered), that would be preferable.

* [ ]  Add contributing docs
  
  * `changelog/README.rst` w/ a style guide and examples, linked from `docs/contributing.rst`
  * Comments in `changelog.rst` ala [attrs](https://raw.githubusercontent.com/python-attrs/attrs/master/CHANGELOG.rst)

For me, this is the big question - how much more complicated does the release process become? My hope is the towncrier step is no more than one additional step (or preferably integrated). Consider adding the detailed instructions to separate sections.

* [ ]  Add to Twine release process

\o/

Again thanks!

[bhrutledge]

I decided to get some practice with regular expressions (esp. look-ahead/behind) and reformatted the existing changelog, which allowed me to remove releases. The GitHub render is now much more useful than the current version, though of course the Sphinx version is even better.

This also includes an attempt to document the versioning schemes.

There are still some TODOs re: contributing and release process, but I'd like to get another sign-off before proceeding.

setuptools uses the name finalize as the action to render the changelog. Maybe consider that for consistency.

I didn't see a whole lot of consistency in my research. Also, it looks like finalize refers to a finalize.py script. With that in mind, I'd rather keep it as changelog, to reflect the thing that is being built.

[bhrutledge]

@pypa/twine-maintainers Can y'all take another look at this before I proceed? #718 (comment)

[sigmavirus24]

Looks good so far. One thing - if we're removing releases we should remove it from docs/requirements.txt

[bhrutledge]

I added contributing instructions for the changelog, heavily edited from pip. Word-smithing/bike-shedding welcome.

https://github.com/pypa/twine/blob/c5c8d9b447f3084e76ae17bb2896455b15e016bf/docs/contributing.rst#submitting-changes

Reviewed before work was completed

[bhrutledge]

I updated the releasing instructions. @pypa/twine-maintainers I think this is (finally) ready for review and merge.