Add openmethane release process using towncrier and GHA

.github/workflows/release.yaml

@@ -0,0 +1,121 @@
+name: Create release
+
+on:
+  workflow_dispatch:
+    inputs:
+      bump_rule:
+        type: choice
+        description: How to bump the project's version (see https://python-poetry.org/docs/cli/#version)
+        options:
+          - patch
+          - minor
+          - major
+          - prepatch
+          - preminor
+          - premajor
+          - prerelease
+        required: true
+
+jobs:
+  bump-version:
+    name: "Bump version and create changelog"
+    if: "!startsWith(github.event.head_commit.message, 'bump:')"
+    runs-on: ubuntu-latest
+    env:
+      CI_COMMIT_EMAIL: "[email protected]"
+    outputs:
+      release-notes: ${{ steps.release-notes.outputs.RELEASE_BODY }}
+      release-version: ${{ steps.release-version.outputs.RELEASE_VERSION }}
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+          token: ${{ secrets.PAT }}
+
+      # towncrier imports the package as part of building so we have to
+      # install the package (to keep things slim, we only install the main
+      # dependencies, which also means that we get a test that we can import
+      # the package with only the compulsory dependencies installed for free)
+      - name: Install Python
+        uses: actions/setup-python@v4
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v2
+      - name: Add version to environment
+        run: |
+          poetry install --only main
+
+      - name: Install towncrier
+        run: |
+          poetry run pip install towncrier
+
+      - name: Determine release version
+        id: release-version
+        run: |
+          BASE_VERSION=`poetry version -s`
+          NEW_VERSION=`poetry version -s ${{ github.event.inputs.bump_rule }}`
+          echo "BASE_VERSION=$BASE_VERSION" >> $GITHUB_ENV
+          echo "NEW_VERSION=$NEW_VERSION" >> $GITHUB_ENV
+          echo "RELEASE_VERSION=$NEW_VERSION" >> $GITHUB_OUTPUT
+
+      # Generates changelog text without removing fragments, for use later in the release
+      - name: Generate release notes
+        id: release-notes
+        run: |
+          echo 'RELEASE_BODY<<EOF' >> $GITHUB_OUTPUT
+          poetry run towncrier build --draft --version "v$NEW_VERSION" >> $GITHUB_OUTPUT
+          echo 'EOF' >> $GITHUB_OUTPUT
+
+      - name: Bump version and generate changelog
+        run: |
+          git config --global user.name "$GITHUB_ACTOR"
+          git config --global user.email "$CI_COMMIT_EMAIL"
+
+          # Bump
+          echo "Bumping version $BASE_VERSION > $NEW_VERSION"
+          poetry run towncrier build --yes --version v$NEW_VERSION
+          git commit -a -m "bump: version $BASE_VERSION -> $NEW_VERSION"
+          git tag v$NEW_VERSION
+
+      - name: Bump to pre-release version
+        run: |
+          git config --global user.name "$GITHUB_ACTOR"
+          git config --global user.email "$CI_COMMIT_EMAIL"
+
+          # Bump to pre-release so that future commits do not have the same
+          # version as the tagged commit
+          NEXT_VERSION=`poetry version -s prerelease`
+          echo "Bumping version $NEW_VERSION > $NEXT_VERSION"
+          git commit -a -m "bump(pre-release): version $NEW_VERSION > $NEXT_VERSION"
+          git push && git push --tags
+
+  publish-release:
+    name: Create release
+    runs-on: ubuntu-latest
+    needs: bump-version
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: Install Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: '3.10'
+      - name: Install poetry
+        uses: abatilo/actions-poetry@v2
+
+      - name: Build package
+        run: |
+          poetry build --no-interaction
+
+      - name: Create release
+        uses: softprops/action-gh-release@v1
+        with:
+          tag_name: v${{ needs.bump-version.outputs.release-version }}
+          body: ${{ needs.bump-version.outputs.release-notes }}
+          token: "${{ secrets.PAT }}"
+          files: |
+            dist/{{ project_name_python }}-${{ needs.bump-version.outputs.release-version }}-py3-none-any.whl
+            dist/{{ project_name_python }}-${{ needs.bump-version.outputs.release-version }}.tar.gz

changelog/README.md

@@ -0,0 +1,41 @@
+# CHANGELOG
+
+This directory contains "news fragments", i.e. short files that contain a small markdown-formatted bit of text that will be
+added to the CHANGELOG when it is next compiled.
+
+The CHANGELOG will be read by users, so this description should be aimed to openmethane users instead of
+describing internal changes which are only relevant to developers. Merge requests in combination with our git history provides additional
+developer-centric information.
+
+Make sure to use phrases in the past tense and use punctuation, examples:
+
+```
+Improved verbose diff output with sequences.
+
+Terminal summary statistics now use multiple colors.
+```
+
+Each file should have a name of the form `<MR>.<TYPE>.md`, where `<MR>` is the merge request number, and `<TYPE>` is one of:
+
+* `feature`: new user facing features, like new command-line options and new behaviour.
+* `improvement`: improvement of existing functionality, usually without requiring user intervention
+* `fix`: fixes a bug.
+* `docs`: documentation improvement, like rewording an entire section or adding missing docs.
+* `deprecation`: feature deprecation.
+* `breaking`: a change which may break existing uses, such as feature removal or behaviour change.
+* `trivial`: fixing a small typo or internal change that might be noteworthy.
+
+So for example: `123.feature.md`, `456.fix.md`.
+
+Since you need the merge request number for the filename, you must submit a MR first. From this MR, you can get the MR number and then create the news file. A single MR can also have multiple news items, for example a given MR may add a feature as well as
+deprecate some existing functionality.
+
+If you are not sure what issue type to use, don't hesitate to ask in your MR.
+
+`towncrier` preserves multiple paragraphs and formatting (code blocks, lists, and so on), but for entries other than
+features it is usually better to stick to a single paragraph to keep it concise. You may also use `MyST` [style
+cross-referencing](https://myst-parser.readthedocs.io/en/latest/syntax/cross-referencing.html) within your news items to link to other
+documentation.
+
+You can also run `towncrier build --draft` to see the draft changelog that will be appended to [docs/source/changelog.md]()
+on the next release.

docs/changelog.md

@@ -0,0 +1,20 @@
+# Changelog
+
+Versions follow [Semantic Versioning](https://semver.org/) (`<major>.<minor>.<patch>`).
+
+Backward incompatible (breaking) changes will only be introduced in major versions
+with advance notice in the **Deprecations** section of releases.
+
+
+<!--
+You should *NOT* be adding new changelog entries to this file, this
+file is managed by towncrier. See changelog/README.md.
+
+You *may* edit previous changelogs to fix problems like typo corrections or such.
+To add a new changelog entry, please see
+https://pip.pypa.io/en/latest/development/contributing/#news-entries,
+noting that we use the `changelog` directory instead of news, md instead
+of rst and use slightly different categories.
+-->
+
+<!-- towncrier release notes start -->