Update release procedure to use towncrier

.gitignore

@@ -4,3 +4,4 @@
 *.swo
 *.DS_Store
 .idea
+venv

CHANGELOG.md

@@ -1,5 +1,3 @@
-## next (------)
-
 ## 0.29.1 (240101)
 
 Bug Fixes:

CONTRIBUTING.md

@@ -12,12 +12,66 @@ discussion before you begin coding. This way you can find out if someone is
 already working on it, or if ideas about the issue have changed since the last
 time it was discussed.
 
+
+## Pull Requests
+
+This project [keeps a changelog](https://keepachangelog.com/), which is meant
+to record changes of interest to users of the software. Therefore every PR
+should include a *news fragment file* (see below), unless its changes are
+of interest only to developers, not users.
+
+To generate a news fragment file, follow the steps below.
+
+1. Be at the root level of the repo, and make sure the Python virtual environment
+   is installed and active. (The installation steps only need to be performed once.)
+
+   ```
+   $ python -m venv venv
+   $ . venv/bin/activate
+   (venv) $ pip install -U pip
+   (venv) $ pip install -r requirements.txt
+   ```
+
+2. Use `branchnews` to generate a news fragment file.
+
+   ```
+   (venv) $ branchnews create
+   ```
+
+   * **If your PR is addressing a specific, numbered issue at GitHub:** Enter the issue
+     number in response to the first prompt.
+   * **Otherwise:** make a blank response to the first prompt, and instead enter your
+     GitHub username at the second prompt.
+
+   When you are asked to choose the *type* of news, you may find the following guidelines
+   helpful:
+
+   * **added:** improvements, new features
+   * **changed:** breaking changes
+   * **fixed:** bug fixes
+   * **deprecated:** an old feature has been deprecated
+   * **removed:** a deprecated feature has been removed
+   * **security:** security fixes
+
+3. Edit the generated file, replacing the auto-generated contents with an entry 
+   describing your changes. Tips:
+
+   * The file will be found in the `changelog.d` directory.
+   * You can use markdown.
+   * Try to keep the entry brief.
+   * Remember that this is for human consumption, and intended more for *users* of the
+     software, than for developers.
+
+4. Commit the file to version control. A simple commit message like `Add news file` will do.
+
+
 ## Code of Conduct
 
 Please note that all participants of this project are expected to follow the
 Code of Conduct. By participating in this project you agree to abide by its
 terms. See [CODE_OF_CONDUCT.md](CODE_OF_CONDUCT.md).
 
+
 ## Legal
 
 Contributions are gladly accepted from their original author. By submitting

changelog.d/.gitignore

@@ -0,0 +1 @@
+!.gitignore

release_procedure.md

@@ -13,40 +13,30 @@ and accept pull requests against it, for last-minute additions to the next
 version.
 
 Step 1. To begin with, you should be on the `main` branch.
-Edit `client/package.json`, setting the version number, and edit
-`CHANGELOG.md`, setting the version number (but not the date), for the
-release. (Do not start a `## next (------)` section yet; you'll do that later.)
+Now make and checkout a release branch, of the form `releases/VERSION`.
+For example, if releasing version `0.26.0`,
+
+    $ git checkout -b releases/0.26.0
 
-Then do an `npm install` so the `package-lock.json` updates accordingly:
+Edit `client/package.json`, setting the version number, and 
+then do an `npm install` so the `package-lock.json` updates accordingly:
 
     $ cd client
     $ npm install
 
-Commit these changes:
+Commit these changes, and push to remote:
 
     $ git add .
     $ git commit -m "Set release version"
-
-Step 2. Now make and checkout a release branch, of the form `releases/VERSION`.
-For example, if releasing version `0.26.0`,
-
-    $ git checkout -b releases/0.26.0
-
-Push to remote:
-
     $ git push origin releases/0.26.0
 
-Step 3. Go back to the `main` branch
+Step 2. Go back to the `main` branch
 
     $ git checkout main
 
 and bump the dev version number. For example, if the release branch is
-`releases/0.26.0`, then
-
-* Go into `client/package.json` and change the version to `0.27.0-dev`.
-* In `CHANGELOG.md`, make a new entry with heading `## next (------)`.
-
-and again update `package-lock.json`:
+`releases/0.26.0`, then go into `client/package.json` and change the version
+to `0.27.0-dev`. Then once again update `package-lock.json`:
 
     $ cd client
     $ npm install
@@ -64,17 +54,23 @@ When you are ready to publish, begin by checking the following items:
 
 * You should be on the release branch.
 * All the changes you want to make it into the release should be committed.
-* Ensure that `CHANGELOG.md` has a complete entry for the release you're about
-  to make, except for the date.
+* Every change that merits an entry in the changelog should have a news fragment
+  file in the `changelog.d` directory. (These should have been added along with
+  each PR!)
 
-Step 1. Now set the date for the `CHANGELOG.md` entry, commit it with a simple
-message stating the version number, and push.
+Step 1. Use `branchnews` to rename news fragment files, and then commit the changes.
 
-    $ git add CHANGELOG.md
-    $ git commit -m "Version 0.26.0"
-    $ git push origin releases/0.26.0
+    (venv) $ branchnews rename
+    (venv) $ git commit -m "Rename branchnews files"
+
+Step 2. Use `towncrier` to build the changelog, commit the changes with
+a message stating the version number, and push.
+
+    (venv) $ towncrier build --version=0.26.0
+    (venv) $ git commit -m "Version 0.26.0"
+    (venv) $ git push origin releases/0.26.0
 
-Step 2. Pushing a version tag to GitHub (next step) will initiate a "pub prep"
+Step 3. Pushing a version tag to GitHub (next step) will initiate a "pub prep"
 test run, which carries out more tests than are ordinarily carried out for PRs.
 In order to avoid having to move the tag in the event of unexpected errors, it
 is good to do a manual run in full "pub prep" mode, before pushing the tag.
@@ -88,10 +84,10 @@ the `pise-build-and-test` workflow, and manually initiate a run. In the
 * Enter the correct version tag for the release
 * Set debug level to 2
 
-After the run completes, you can inspect the uploaded artifacts if you want,
-but delete them when you are done.
+After the run completes, you can inspect the uploaded artifacts if you want.
+In any case, delete them before proceeding.
 
-Step 3. Add a tag, which must be of the form
+Step 4. Add a tag, which must be of the form
 `vMAJOR.MINOR.PATCH(-LABEL)` (`LABEL` part optional), and push the tag to
 GitHub. For example,
 
@@ -103,10 +99,10 @@ that works toward publication. It begins with jobs that build and test all the
 products. The actual publication job, however, will not run until it has been
 approved by a project maintainer.
 
-Step 4. Approve the publication job, and confirm availability of the published
+Step 5. Approve the publication job, and confirm availability of the published
 products at Docker Hub and npm, after it completes.
 
-Step 5. Return to the `main` branch, and merge the release branch.
+Step 6. Return to the `main` branch, and merge the release branch.
 There should be merge conflicts in the `package.json` and `package-lock.json`
 files under the `client` dir, regarding the version number. We want to keep the
 version from the `main` branch:
@@ -116,6 +112,4 @@ version from the `main` branch:
     $ git checkout --ours client/package*.json
     $ git add client/package*.json
 
-Then manually resolve any merge conflict in `CHANGELOG.md` -- *without changing
-the entry for the version that was just released* -- and complete the merge.
-Finally, push to `main` one more time.
+Complete the merge, and finally push to `main` one more time.

requirements.txt

@@ -0,0 +1,4 @@
+# The venv at the root level of this project is just for
+# building the changelog.
+towncrier>=23.11.0
+branchnews>=0.1.0

towncrier.toml

@@ -0,0 +1,37 @@
+[tool.towncrier]
+directory = "changelog.d"
+filename = "CHANGELOG.md"
+start_string = "<!-- towncrier release notes start -->\n"
+underlines = ["", "", ""]
+title_format = "## [{version}](https://github.com/proofscape/pise/tree/{version}) - {project_date}"
+issue_format = "[#{issue}](https://github.com/proofscape/pise/issues/{issue})"
+
+[[tool.towncrier.type]]
+directory = "added"
+name = "Added"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "changed"
+name = "Changed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "fixed"
+name = "Fixed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "deprecated"
+name = "Deprecated"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "removed"
+name = "Removed"
+showcontent = true
+
+[[tool.towncrier.type]]
+directory = "security"
+name = "Security"
+showcontent = true