Skip to content
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

ci(release): add release workflow and versioning script #18

Merged
merged 1 commit into from
Apr 25, 2023

Conversation

wpbonelli
Copy link
Contributor

@wpbonelli wpbonelli commented Apr 22, 2023

  • Add .github/workflows/release.yml to automate releases. The workflow is triggered when a branch matching semantic version format and prefixed with v (e.g. v0.1.1) is pushed. The steps happen automatically for the most part (italics), with maintainer action (bold) only needed to trigger the process and then review/greenlight each stage

    1. Push release branch
    2. Lint, update version strings, build, test, update changelog, and open PR against main
    3. Merge to main (not squash/rebase, to preserve history)
    4. Draft GitHub release post
    5. Publish GitHub release
    6. Publish package to PyPI
    7. Open PR against develop branch from main to reset for next development phase, incrementing minor version number and resetting patch number to 0
    8. Merge to develop (not squash/rebase)
  • Use git-cliff to autogenerate changelog. On the next release this will add a HISTORY.md cumulative changelog file.

  • Add scripts/pull_request_prepare.py which runs black on the modflowapi main module. Could also isort but this caused even more merge conflicts, and was not previously done, so disabled for now. Add isort to the lint dependency group in pyproject.toml though.

  • Add scripts/update_version.py to update version strings embedded in the modflowapi module and CITATION.cff. This is used in the automatic release workflow above and should generally not need to run locally. Example usage:

    $ python scripts/update_version.py -v 0.1.1
    Updated /***/modflowapi/modflowapi/version.py to version 0.1.1
    Updated /***/modflowapi/CITATION.cff to version 0.1.1

    It can also be used to get the current version with --get (short -g)

    $ python scripts/update_version.py -g
    0.1.1

Notes

Merge conflicts & preserving history

On the first automated release, there will likely be merge conflicts to resolve in the PR created on main. This is because when releases are squashed into main, it diverges from develop.

In the future, releases can merge (not squash) to main to avoid this, then merge (again not squash) the development reset PR back into develop. (The cumulative changelog may also need manual correction the first time for the same reason.)

Major, minor & patch releases

The workflow here should work for releases of all three levels, with major and minor releases generally expected to branch from develop, where the main development efforts occur, and patch (micro) releases branching from main for narrow-scoped bug-fixes.

PyPI authentication

The release.yml workflow does not use twine username/password to authenticate with PyPI during the publish step. Instead it is assumed that modflowapi has been configured in PyPI to use trusted publishing. Repository secrets for twine username/password are not needed.

Testing

Full procedure test run (except publishing to PyPI):

@wpbonelli wpbonelli force-pushed the releases branch 3 times, most recently from c4ad8c3 to b005559 Compare April 24, 2023 16:14
@wpbonelli wpbonelli marked this pull request as ready for review April 24, 2023 16:49
@wpbonelli wpbonelli merged commit ab73ed6 into MODFLOW-USGS:develop Apr 25, 2023
@wpbonelli wpbonelli deleted the releases branch April 25, 2023 14:07
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.

1 participant