-
-
Notifications
You must be signed in to change notification settings - Fork 517
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
i2885 towncrier
support and release workflow integration
#3469
base: develop
Are you sure you want to change the base?
i2885 towncrier
support and release workflow integration
#3469
Conversation
Let Towncrier handle it after the version has been updated
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 ( |
Codecov ReportAll modified and coverable lines are covered by tests ✅
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 ☔ View full report in Codecov by Sentry. |
The unreleased section will be removed from this section when pybamm-team/PyBaMM#3469 is merged. It will fix the heading normalisation too.
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 anewsfragments/
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:
Towncrier
runs only in theupdate_version.yml
workflow and is strictly not meant to be run locally (unless manual intervention is required).update_version.py
.Towncrier
picks up that version automatically, builds a CHANGELOG from the entries in thenewsfragments/
directory, and then deletes those fragments. The changes are then committed and a PR is then made that points to thedevelop
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 thedevelop
branch in the meantime in different PRs, the scheduled PR branch should be rebased on top of thedevelop
branch and extra entries have to be added in theCHANGELOG.md
file manually. The PR can then be merged safely as long as there are no outstanding news fragments.newsfragments/
directory will start accumulating files. If an rcX release is required, theupdate_version.yml
workflow is triggered manually, the version is updated in multiple files, andTowncrier
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 thenewsfragments/
file would be empty. A maintainer has to manually update the version string in theCHANGELOG.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. RunningTowncrier
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 thenewsfragments/
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.
Key checklist:
$ 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)$ python run-tests.py --all
(or$ nox -s tests
)$ 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: