i2885 towncrier support and release workflow integration

.github/PULL_REQUEST_TEMPLATE.md

@@ -6,11 +6,12 @@ Fixes # (issue)
 
 ## Type of change
 
-Please add a line in the relevant section of [CHANGELOG.md](https://github.com/pybamm-team/PyBaMM/blob/develop/CHANGELOG.md) to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.
+Please add a [news entry](https://docs.pybamm.org/en/latest/source/user_guide/contributing.html) using `towncrier` in the [`newsfragments/` directory](https://github.com/pybamm-team/PyBaMM/tree/develop/newsfragments/) for the relevant section in the [CHANGELOG.md](https://github.com/pybamm-team/PyBaMM/blob/develop/CHANGELOG.md) to document the change (include PR #) - note reverse order of PR #s. If necessary, also add it to the list of breaking changes.
 
 - [ ] New feature (non-breaking change which adds functionality)
 - [ ] Optimization (back-end change that speeds up the code)
 - [ ] Bug fix (non-breaking change which fixes an issue)
+- [ ] Breaking change (fix or feature that would cause existing functionality to not work as expected)
 
 # Key checklist:
 

.github/release_workflow.md

@@ -13,7 +13,11 @@ This file contains the workflow required to make a `PyBaMM` release on GitHub, P
    - `vcpkg.json`
    - `CHANGELOG.md`
 
-      These changes will be automatically pushed to a new branch `vYY.MM` and a PR from `vvYY.MM` to `develop` will be created (to sync the branches).
+   and the `CHANGELOG.md` file will be generated via [Towncrier](https://towncrier.readthedocs.io/en/stable/) for the updated version string. The news fragments will be deleted at the end of the process for further release candidates or for the actual release.
+
+   If further commits and changes are required to be made to the `develop` branch, the pull request branch titled "Make release `vYY.MMrc0`" will require manual updates to the `CHANGELOG.md` file and related sorting of pull requests (i.e., not using `Towncrier`), since the `newsfragments/` directory shall remain empty after the automated release process and the `develop` branch would have updated with new commits.
+
+   These changes will be automatically pushed to a new branch `vYY.MM` and a PR from `vvYY.MM` to `develop` will be created (to sync the branches).
 
 2. Create a new GitHub _pre-release_ with the tag `vYY.MMrc0` from the `vYY.MM` branch and a description copied from `CHANGELOG.md`.
 
@@ -23,11 +27,11 @@ This file contains the workflow required to make a `PyBaMM` release on GitHub, P
 
 If a new release candidate is required after the release of `rc0` -
 
-1. Fix a bug in `vYY.MM` (no new features should be added to `vYY.MM` once `rc0` is released) and `develop` individually.
+1. Fix a bug in `vYY.MM` (no new features should be added to `vYY.MM` once `rc0` is released) and `develop` individually and add a news fragment if needed.
 
 2. Run `update_version.yml` manually while using `append_to_tag` to specify the release candidate version number (`rc1`, `rc2`, ...).
 
-3. This will increment the version to `vYY.MMrcX` by running `scripts/update_version.py` in the following files -
+   This will increment the version to `vYY.MMrcX` by running `scripts/update_version.py` in the following files -
 
    - `pybamm/version.py`
    - `docs/conf.py`
@@ -36,19 +40,21 @@ If a new release candidate is required after the release of `rc0` -
    - `vcpkg.json`
    - `CHANGELOG.md`
 
-      These changes will be automatically pushed to the existing `vYY.MM` branch and a PR from `vvYY.MM` to `develop` will be created (to sync the branches).
+   and the `CHANGELOG.md` file will be generated via [Towncrier](https://towncrier.readthedocs.io/en/stable/) for the updated version string. The news fragments will be deleted at the end of the process for further release candidates or for the actual release.
 
-4. Create a new GitHub _pre-release_ with the same tag (`vYY.MMrcX`) from the `vYY.MM` branch and a description copied from `CHANGELOG.md`.
+   These changes will be automatically pushed to the existing `vYY.MM` branch and a PR from `vvYY.MM` to `develop` will be created (to sync the branches).
 
-5. This release will automatically trigger `publish_pypi.yml` and create a _pre-release_ on PyPI.
+3. Create a new GitHub _pre-release_ with the same tag (`vYY.MMrcX`) from the `vYY.MM` branch and a description copied from `CHANGELOG.md`.
+
+4. This release will automatically trigger `publish_pypi.yml` and create a _pre-release_ on PyPI.
 
 ## Actual release (manual)
 
 Once satisfied with the release candidates -
 
 1. Run `update_version.yml` manually, leaving the `append_to_tag` field blank ("") for an actual release.
 
-2. This will increment the version to `vYY.MMrcX` by running `scripts/update_version.py` in the following files -
+   This will increment the version to `vYY.MM` by running `scripts/update_version.py` in the following files -
 
    - `pybamm/version.py`
    - `docs/conf.py`
@@ -57,7 +63,9 @@ Once satisfied with the release candidates -
    - `vcpkg.json`
    - `CHANGELOG.md`
 
-      These changes will be automatically pushed to the existing `vYY.MM` branch and a PR from `vvYY.MM` to `develop` will be created (to sync the branches).
+   If and after the release candidates are satisfactory, the `newsfragments/` directory shall not contain any new entries and the CHANGELOG shall have been updated at the time of the release candidates already. In this case, manually edit the `CHANGELOG.md` file to remove the `rcX` suffix from the version string to be used for the actual release (i.e., `vYY.MMrcX` -> `vYY.MM`), and edit the date of the release as necessary.
+
+   These changes will be automatically pushed to the existing `vYY.MM` branch and a PR from `vvYY.MM` to `develop` will be created (to sync the branches).
 
 3. Next, a PR from `vYY.MM` to `main` will be generated that should be merged once all the tests pass.
 

.github/workflows/lychee_url_checker.yml

@@ -44,6 +44,7 @@ jobs:
             --exclude https://www.rse.ox.ac.uk
             --accept 200,429
             --exclude-path ./CHANGELOG.md
+            --exclude-path newsfragments/*.md
             --exclude-path ./scripts/update_version.py
             --exclude-path asv.conf.json
             --exclude-path docs/conf.py

.github/workflows/update_version.yml

@@ -17,7 +17,7 @@ jobs:
     runs-on: ubuntu-latest
 
     steps:
-      - name: Get current date for the first release candidate
+      - name: Get current date for the first release candidate (rc0)
         if: github.event_name == 'schedule'
         run: |
           echo "VERSION=$(date +'v%y.%-m')rc0" >> $GITHUB_ENV
@@ -42,16 +42,25 @@ jobs:
       - name: Set up Python
         uses: actions/setup-python@v5
         with:
-          python-version: 3.8
+          python-version: 3.11
 
       - name: Install dependencies
         run: |
-          pip install wheel
+          pip install wheel towncrier
           pip install --editable ".[all]"
 
       - name: Update version
         run: python scripts/update_version.py
 
+      - name: Build the CHANGELOG and purge news fragments
+        # On schedule, we bump to rc0 and therefore we need to build the CHANGELOG for the first time.
+        # On workflow_dispatch, we bump to rcX and therefore we need to update the CHANGELOG with the
+        # latest news fragments and delete them.
+        # on workflow_dispatch for the actual release (when the append_to_tag input is empty), we do not run this step, since
+        # we manually edit the version number in the CHANGELOG (since it would have already been built by the previous RC).
+        if: github.event_name == 'schedule' || (github.event_name == 'workflow_dispatch' && github.event.inputs.append_to_tag != '')
+        run: python -m towncrier build --yes
+
       - uses: EndBug/add-and-commit@v9
         if: github.event_name == 'schedule'
         with: