Configure towncrier to auto generate release notes

Fixes ethereum#754, ethereum#101

.github/PULL_REQUEST_TEMPLATE.md

@@ -10,10 +10,10 @@
 [//]: # (Stay ahead of things, add list items here!)
 - [ ] Clean up commit history
 
-[//]: # (For important changes, please add a new entry to the running release notes PR)
-[//]: # (You can find the current one using: https://github.com/ethereum/trinity/pulls?q=is%3Aopen+is%3Apr+label%3A%22Release+Notes%22 )
+[//]: # (For important changes that should go into the release notes please add a newsfragment file as explained here: https://github.com/ethereum/trinity/blob/master/newsfragments/README.md)
+
 [//]: # (See: https://trinity-client.readthedocs.io/en/latest/contributing.html#pull-requests)
-- [ ] Add entry to the [release notes PR](https://github.com/ethereum/trinity/pulls?q=is%3Aopen+is%3Apr+label%3A%22Release+Notes%22)
+- [ ] Add entry to the [release notes](https://github.com/ethereum/trinity/blob/master/newsfragments/README.md)
 
 #### Cute Animal Picture
 

Makefile

@@ -44,6 +44,8 @@ doctest:
 	cd docs/; sphinx-build -T -b doctest . _build/doctest
 
 validate-docs: build-docs doctest
+	./newsfragments/validate_files.py
+	towncrier --draft
 
 docs: build-docs
 	open docs/_build/html/index.html
@@ -58,7 +60,13 @@ package: clean
 release: clean
 	CURRENT_SIGN_SETTING=$(git config commit.gpgSign)
 	git config commit.gpgSign true
-	bumpversion $(bump)
+	# Let UPCOMING_VERSION be the version that comes out of the bump
+	$(eval UPCOMING_VERSION=$(shell bumpversion $(bump) --dry-run --list | grep new_version= | sed 's/new_version=//g'))
+	# Now generate the release notes to have it included in the release commit
+	towncrier --yes --version $(UPCOMING_VERSION)
+	# We need --allow-dirty because of the generated release_notes but it is safe because the
+	# previous dry-run runs *without* --allow-dirty which ensures it's really just the release notes
+	bumpversion --allow-dirty $(bump)
 	git push upstream && git push upstream --tags
 	python setup.py sdist bdist_wheel
 	twine upload dist/*

docs/contributing.rst

@@ -90,8 +90,8 @@ GitHub interface and make sure all tests are passing. In general pull requests t
 do not pass the CI build yet won't get reviewed unless explicitly requested.
 
 If the pull request introduces changes that should be reflected in the release notes,
-please add a line to the *Unreleased (from source)* section of the
-`release_notes file<https://github.com/ethereum/trinity/blob/master/docs/release_notes.rst>_`
+please add a `newsfragment` file as explained
+`here<https://github.com/ethereum/trinity/blob/master/newsfragments/README.md>_`
 
 If possible, the change to the release notes file should be included in the commit that introduces the
 feature or bugfix.

docs/release_notes.rst

@@ -3,6 +3,9 @@ Release Notes
 
 Trinity is moving fast. Read up on all the latest improvements.
 
+.. towncrier release notes start
+
+
 v0.1.0-alpha.25
 --------------------------
 

newsfragments/754.doc.rst

@@ -0,0 +1,2 @@
+Setup towncrier to generate release notes from fragment files to  ensure a higher standard
+for release notes.

newsfragments/README.md

@@ -0,0 +1,25 @@
+This directory collects "newsfragments": short files that each contain
+a snippet of ReST-formatted text that will be added to the next
+release notes. This should be a description of aspects of the change
+(if any) that are relevant to users. (This contrasts with the
+commit message and PR description, which are a description of the change as
+relevant to people working on the code itself.)
+
+Each file should be named like `<ISSUE>.<TYPE>.rst`, where
+`<ISSUE>` is an issue numbers, and `<TYPE>` is one of:
+
+* `feature`
+* `bugfix`
+* `doc`
+* `removal`
+* `misc`
+
+So for example: `123.feature.rst`, `456.bugfix.rst`
+
+If the PR fixes an issue, use that number here. If there is no issue,
+then open up the PR first and use the PR number for the newsfragment.
+
+Note that the `towncrier` tool will automatically
+reflow your text, so don't try to do any fancy formatting. Run
+ `towncrier --draft` to get a preview of what the release notes entry
+ will look like in the final release notes.

newsfragments/validate_files.py

@@ -0,0 +1,31 @@
+#!/usr/bin/env python3
+
+# Towncrier silently ignores files that do not match the expected ending.
+# We use this script to ensure we catch these as errors in CI.
+
+import os
+import pathlib
+
+ALLOWED_EXTENSIONS = (
+    'feature.rst',
+    'bugfix.rst',
+    'doc.rst',
+    'removal.rst',
+    'misc.rst',
+)
+
+ALLOWED_FILES = (
+    'validate_files.py',
+    'README.md',
+)
+
+THIS_DIR = pathlib.Path(__file__).parent
+
+for file in THIS_DIR.iterdir():
+
+    if file.name in ALLOWED_FILES:
+        continue
+
+    full_extension = "".join(file.suffixes)
+    if full_extension not in ALLOWED_EXTENSIONS:
+        raise Exception(f"Unexpected file: {file}")

pyproject.toml

@@ -0,0 +1,12 @@
+[tool.towncrier]
+# Usage:
+# - PRs should drop a file like "issuenumber.feature" in newsfragments
+#   (or "bugfix", "doc", "removal", "misc"; misc gets no text, we can
+#    customize this)
+# - At release time after bumping version number, run: towncrier
+#   (or towncrier --draft)
+package = "trinity"
+filename = "docs/release_notes.rst"
+directory = "newsfragments"
+underlines = ["-", "~", "^"]
+issue_format = "`#{issue} <https://github.com/ethereum/trinity/issues/{issue}>`__"

setup.py

@@ -69,6 +69,7 @@
         "Sphinx>=1.5.5,<1.8.0",
         "sphinx_rtd_theme>=0.1.9",
         "sphinxcontrib-asyncio>=0.2.0",
+        "towncrier>=19.2.0, <20",
     ],
     'dev': [
         "bumpversion>=0.5.3,<1",