i2885 `towncrier` support and release workflow integration

[agriyakhetarpal]

Description

This PR adds Towncrier to automatically update the CHANGELOG using news fragments. The current CHANGELOG file is modified to fit the standard template of Towncrier (therefore eliminating the need to use and maintain a custom jinja template in the wake of breaking changes). Through the new CHANGELOG management system; news fragments will be added to relevant PRs that add features, optimizations, perform bug fixes, or implement breaking changes—instead of adding CHANGELOG entries. This prevents merge conflicts at the time of merging PRs.

With the new workflow, each time a PR with a news fragment is merged into the develop branch, it stays there in a newsfragments/ folder, which keeps collecting news fragments between releases. The Unreleased section of the CHANGELOG is removed in favour of this system.

At the time of creating a release, the workflow works in this fashion:

1. Towncrier runs only in the update_version.yml workflow and is strictly not meant to be run locally (unless manual intervention is required).
2. On automated releases (rc0), the PyBaMM version is incremented in the aforementioned workflow via update_version.py. Towncrier picks up that version automatically, builds a CHANGELOG from the entries in the newsfragments/ directory, and then deletes those fragments. The changes are then committed and a PR is then made that points to the develop branch. This scheduled PR is supposed to be merged as soon as possible to avoid conflicts. However, if merging takes (or will take) time and further commits are pushed to the develop branch in the meantime in different PRs, the scheduled PR branch should be rebased on top of the develop branch and extra entries have to be added in the CHANGELOG.md file manually. The PR can then be merged safely as long as there are no outstanding news fragments.
3. Now, there are two possible pathways for the next release:
   • Further release candidates: assuming the development and resolution of bug fixes continues, the newsfragments/ directory will start accumulating files. If an rcX release is required, the update_version.yml workflow is triggered manually, the version is updated in multiple files, and Towncrier inserts another section in the CHANGELOG, this time for the rcX version, and collates the new news entries (the ones that were pushed after the deletion of the previous ones at the time of release of rc[X-1]). 3.2: An actual release (non-RC): once the release candidate(s) are satisfactory for all developers and users, the CHANGELOG would have already been built with Towncrier at the time of the release candidates and the newsfragments/ file would be empty. A maintainer has to manually update the version string in the CHANGELOG.md file from rcX to the non-RC version (e.g., from 24.1rc0 to 24.1) and adjust the date of the release as needed. Running Towncrier is not required. This should be fine, considering the fact that the actual release workflow is already manual.

After and during the releases have been created, activity on the develop branch remains unaffected and news entries keep getting added to the newsfragments/ directory.

Addendum: some of the nuances of this pipeline come from the fact that Towncrier exits early with an error message if a CHANGELOG for a particular has already been built. It cannot handle adding updates for the same version of a project as of now.

Fixes #2885

Type of change

Please add a line in the relevant section of CHANGELOG.md to document the change (include PR #) - note reverse order of PR #s. If necessary, also add to the list of breaking changes.

• [x] 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)

Key checklist:

• [x] No style issues: $ pre-commit run (or $ nox -s pre-commit) (see CONTRIBUTING.md for how to set this up to run automatically when committing locally, in just two lines of code)
• [x] All tests pass: $ python run-tests.py --all (or $ nox -s tests)
• [x] The documentation builds: $ python run-tests.py --doctest (or $ nox -s doctests)

You can run integration tests, unit tests, and doctests together at once, using $ python run-tests.py --quick (or $ nox -s quick).

Further checks:

• [x] Code is commented, particularly in hard-to-understand areas
• [ ] Tests added that prove fix is effective or that feature works

[agriyakhetarpal]

I have tried to elaborate the process as cleanly as possible above, please let me know if there are any questions! Some of the links will fail the link checker here, which will be fixed upon merging. It is obviously possible that I may have missed something and may not have covered all cases since our release system after #3249 is a mix of both automated and manual releases, but this will only be applicable at the time of the next release (v24.1rc0), so we will have a lot of time to fix any loose ends.

[codecov[bot]]

Codecov Report

All modified and coverable lines are covered by tests :white_check_mark:

Comparison is base (256747c) 99.59% compared to head (703c6fb) 99.59%.

Additional details and impacted files

@@           Coverage Diff            @@
##           develop    #3469   +/-   ##
========================================
  Coverage    99.59%   99.59%           
========================================
  Files          258      258           
  Lines        20778    20778           
========================================
  Hits         20693    20693           
  Misses          85       85           

:umbrella: View full report in Codecov by Sentry.
:loudspeaker: Have feedback on the report? Share it here.