From d569b015b1bb0a403e2162d3e5f609e2c9be2682 Mon Sep 17 00:00:00 2001
From: Jason Carver <ut96caarrs@snkmail.com>
Date: Thu, 12 Sep 2019 15:18:48 -0700
Subject: [PATCH] Split documentation build into separate step

---
 Makefile                        | 17 +++++++++--------
 docs/contributing.rst           | 14 +++++++++++++-
 newsfragments/validate_files.py | 16 +++++++++++++---
 3 files changed, 35 insertions(+), 12 deletions(-)

diff --git a/Makefile b/Makefile
index 27614ca8a5..fe526c95b4 100644
--- a/Makefile
+++ b/Makefile
@@ -60,19 +60,20 @@ package: clean
 	python setup.py sdist bdist_wheel
 	python scripts/release/test_package.py
 
-release: clean
-	CURRENT_SIGN_SETTING=$(git config commit.gpgSign)
-	git config commit.gpgSign true
+notes:
 	# 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 but it is safe because the
-	# previous dry-run runs *without* --allow-dirty which ensures it's really just the release notes
-	# file that we are allowing to sit here dirty, waiting to get included in the release commit.
-	bumpversion --allow-dirty $(bump)
+	git commit -m "Compile release notes"
+
+release: clean
+	./newsfragments/validate_files.py is-empty
+	CURRENT_SIGN_SETTING=$(git config commit.gpgSign)
+	git config commit.gpgSign true
+	bumpversion $(bump)
 	git push upstream && git push upstream --tags
 	python setup.py sdist bdist_wheel
 	twine upload dist/*
@@ -86,4 +87,4 @@ sdist: clean
 	ls -l dist
 
 install-git-lfs:
-	apt-get install -y git-lfs
\ No newline at end of file
+	apt-get install -y git-lfs
diff --git a/docs/contributing.rst b/docs/contributing.rst
index b1648e6aad..5b491e4442 100644
--- a/docs/contributing.rst
+++ b/docs/contributing.rst
@@ -139,10 +139,22 @@ Before releasing a new version, build and test the package that will be released
     # Preview the upcoming release notes
     towncrier --draft
 
+Compile the release notes
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+After confirming that the release package looks okay, compile the release notes:
+
+.. code:: sh
+
+    make notes bump=$$VERSION_PART_TO_BUMP$$
+
+You may need to fix up any broken release note fragments before committing. Keep
+running make build-docs until it passes, then commit and carry on.
+
 Push the release to github & pypi
 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
 
-After confirming that the release package looks okay, release a new version:
+After committing the compiled release notes, release a new version:
 
 .. code:: sh
 
diff --git a/newsfragments/validate_files.py b/newsfragments/validate_files.py
index c6695bc77c..e0c378ef5a 100755
--- a/newsfragments/validate_files.py
+++ b/newsfragments/validate_files.py
@@ -5,6 +5,7 @@
 
 import os
 import pathlib
+import sys
 
 ALLOWED_EXTENSIONS = {
     '.bugfix.rst',
@@ -22,11 +23,20 @@
 
 THIS_DIR = pathlib.Path(__file__).parent
 
+num_args = len(sys.argv) - 1
+assert num_args in {0, 1}
+if num_args == 1:
+    assert sys.argv[1] in ('is-empty', )
+
 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:
+    elif num_args == 0:
+        full_extension = "".join(fragment_file.suffixes)
+        if full_extension not in ALLOWED_EXTENSIONS:
+            raise Exception(f"Unexpected file: {fragment_file}")
+    elif sys.argv[1] == 'is-empty':
         raise Exception(f"Unexpected file: {fragment_file}")
+    else:
+        raise RuntimeError("Strange: arguments {sys.argv} were validated, but not found")