From 9b1609cc8b1fdf95c1ba209309b5e6ad06c0ed85 Mon Sep 17 00:00:00 2001 From: Steve Kieffer Date: Thu, 18 Jan 2024 18:23:51 -0500 Subject: [PATCH] Update release procedure to use `towncrier` --- .gitignore | 1 + CHANGELOG.md | 2 -- CONTRIBUTING.md | 54 ++++++++++++++++++++++++++++++++++ changelog.d/.gitignore | 1 + release_procedure.md | 66 +++++++++++++++++++----------------------- requirements.txt | 4 +++ towncrier.toml | 37 +++++++++++++++++++++++ 7 files changed, 127 insertions(+), 38 deletions(-) create mode 100644 changelog.d/.gitignore create mode 100644 requirements.txt create mode 100644 towncrier.toml diff --git a/.gitignore b/.gitignore index 0dca3c78..2e1e253e 100644 --- a/.gitignore +++ b/.gitignore @@ -4,3 +4,4 @@ *.swo *.DS_Store .idea +venv diff --git a/CHANGELOG.md b/CHANGELOG.md index 2ec5f8e6..c8cd4a88 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,3 @@ -## next (------) - ## 0.29.1 (240101) Bug Fixes: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 437fcdaf..1371a43f 100644 --- a/CONTRIBUTING.md +++ b/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 diff --git a/changelog.d/.gitignore b/changelog.d/.gitignore new file mode 100644 index 00000000..f935021a --- /dev/null +++ b/changelog.d/.gitignore @@ -0,0 +1 @@ +!.gitignore diff --git a/release_procedure.md b/release_procedure.md index c448e0ec..323de0c6 100644 --- a/release_procedure.md +++ b/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. diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 00000000..7cd45315 --- /dev/null +++ b/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 diff --git a/towncrier.toml b/towncrier.toml new file mode 100644 index 00000000..e5ada9f0 --- /dev/null +++ b/towncrier.toml @@ -0,0 +1,37 @@ +[tool.towncrier] +directory = "changelog.d" +filename = "CHANGELOG.md" +start_string = "\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