Setup towncrier to generate release notes

.circleci/config.yml

@@ -36,12 +36,12 @@ common: &common
         key: cache-{{ .Environment.CIRCLE_JOB }}-{{ checksum "setup.py" }}-{{ checksum "tox.ini" }}
 
 jobs:
-  doctest:
+  docs:
     <<: *common
     docker:
       - image: circleci/python:3.6
         environment:
-          TOXENV: doctest
+          TOXENV: docs
   lint:
     <<: *common
     docker:
@@ -70,7 +70,7 @@ workflows:
   version: 2
   test:
     jobs:
-      - doctest
+      - docs
       - lint
       - py36-core
       - py37-core

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,6 +6,16 @@ Issue #
 
 Summary of approach.
 
+### To-Do
+
+[//]: # (Stay ahead of things, add list items here!)
+- [ ] Clean up commit history
+
+[//]: # (For important changes that should go into the release notes please add a newsfragment file as explained here: https://github.com/ethereum/<REPO_NAME>/blob/master/newsfragments/README.md)
+
+[//]: # (See: https://<RTD_NAME>.readthedocs.io/en/latest/contributing.html#pull-requests)
+- [ ] Add entry to the [release notes](https://github.com/ethereum/<REPO_NAME>/blob/master/newsfragments/README.md)
+
 #### Cute Animal Picture
 
 ![put a cute animal picture link inside the parentheses]()

Makefile

@@ -41,6 +41,8 @@ build-docs:
 	$(MAKE) -C docs clean
 	$(MAKE) -C docs html
 	$(MAKE) -C docs doctest
+	./newsfragments/validate_files.py
+	towncrier --draft --version preview
 
 docs: build-docs
 	open docs/_build/html/index.html
@@ -49,13 +51,23 @@ linux-docs: build-docs
 	xdg-open docs/_build/html/index.html
 
 release: clean
+	CURRENT_SIGN_SETTING=$(git config commit.gpgSign)
 	git config commit.gpgSign true
-	bumpversion $(bump)
+	# Let UPCOMING_VERSION be the version that is used for the current 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 them included in the release commit
+	towncrier --yes --version $(UPCOMING_VERSION)
+	# Before we bump the version, make sure that the towncrier-generated docs will build
+	make build-docs
+	# We need --allow-dirty because of the generated release_notes file that goes into the release
+	# commit. No other files are added accidentially. The dry-run still runs *without* --allow-dirty
+	bumpversion --allow-dirty $(bump)
 	git push upstream && git push upstream --tags
 	python setup.py sdist bdist_wheel
 	twine upload dist/*
 	git config commit.gpgSign "$(CURRENT_SIGN_SETTING)"
 
+
 dist: clean
 	python setup.py sdist bdist_wheel
 	ls -l dist

README.md

@@ -88,9 +88,7 @@ The version format for this repo is `{major}.{minor}.{patch}` for stable, and
 To issue the next version in line, specify which part to bump,
 like `make release bump=minor` or `make release bump=devnum`. This is typically done from the
 master branch, except when releasing a beta (in which case the beta is released from master,
-and the previous stable branch is released from said branch). To include changes made with each
-release, update "docs/releases.rst" with the changes, and apply commit directly to master 
-before release.
+and the previous stable branch is released from said branch).
 
 If you are in a beta version, `make release bump=stage` will switch to a stable.
 

docs/index.rst

@@ -10,7 +10,7 @@ Contents
     :maxdepth: 3
 
     <MODULE_NAME>
-    releases
+    release_notes
 
 
 Indices and tables

docs/release_notes.rst

@@ -1,6 +1,8 @@
 Release Notes
 =============
 
+.. towncrier release notes start
+
 v0.1.0-alpha.1
 --------------
 

newsfragments/README.md

@@ -0,0 +1,26 @@
+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`
+* `performance`
+* `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,32 @@
+#!/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 = {
+    '.bugfix.rst',
+    '.doc.rst',
+    '.feature.rst',
+    '.misc.rst',
+    '.performance.rst',
+    '.removal.rst',
+}
+
+ALLOWED_FILES = {
+    'validate_files.py',
+    'README.md',
+}
+
+THIS_DIR = pathlib.Path(__file__).parent
+
+for fragment_file in THIS_DIR.iterdir():
+
+    if fragment_file.name in ALLOWED_FILES:
+        continue
+
+    full_extension = "".join(fragment_file.suffixes)
+    if full_extension not in ALLOWED_EXTENSIONS:
+        raise Exception(f"Unexpected file: {fragment_file}")

pyproject.toml

@@ -0,0 +1,39 @@
+[tool.towncrier]
+# Read https://github.com/ethereum/<REPO_NAME>/newsfragments/README.md for instructions
+package = "<MODULE_NAME>"
+filename = "docs/release_notes.rst"
+directory = "newsfragments"
+underlines = ["-", "~", "^"]
+issue_format = "`#{issue} <https://github.com/ethereum/<REPO_NAME>/issues/{issue}>`__"
+
+# Configure all default sections plus an extra one for performance improvements.
+
+[[tool.towncrier.type]]
+directory = "feature"
+name = "Features"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "bugfix"
+name = "Bugfixes"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "performance"
+name = "Performance improvements"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "doc"
+name = "Improved Documentation"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removal"
+name = "Deprecations and Removals"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "misc"
+name = "Miscellaneous internal changes"
+showcontent = false

setup.py

@@ -20,6 +20,7 @@ extras_require = {
     'doc': [
         "Sphinx>=1.6.5,<2",
         "sphinx_rtd_theme>=0.1.9",
+        "towncrier>=19.2.0, <20",
     ],
     'dev': [
         "bumpversion>=0.5.3,<1",

tox.ini

@@ -2,7 +2,7 @@
 envlist=
     py{36,37,py3}-core
     lint
-    doctest
+    docs
 
 [isort]
 combine_as_imports=True
@@ -23,15 +23,15 @@ ignore=
 usedevelop=True
 commands=
     core: pytest {posargs:tests/core}
-    doctest: make -C {toxinidir}/docs doctest
+    docs: make build-docs
 basepython =
-    doctest: python
+    docs: python
     py36: python3.6
     py37: python3.7
     pypy3: pypy3
 extras=
     test
-    doctest: doc
+    docs: doc
 whitelist_externals=make
 
 [testenv:lint]