doc: Github release workflows
LecrisUT opened this issue · comments
It would be nice to document some Github workflow designs that the user can use. I have not included the example yamls, since I am not sure about the cli interface to run this, after studying it a bit, or if someone comments with some implementation I will update this post.
on.workflow_dispatch
Uses inputs to specify what version to tag (and on which commit/branch to checkout).
Steps:
- Update the
Changelog.md
- Create/Push a new commit
- Create a new tag
- Create github release
Pros:
- Most flexible release cycle
Cons:
- Cannot trigger CI with
on.push.tag
(unless PAT is used)
on.push.tag
Current release cycle is already configured
Steps:
- Create github release
- Update the
Changelog.md
for next release cycle (tagging the date for old cycle) - Create/Push new commit
Pros:
- Simple workflow
- Can integrate with other workflows
- Signable git tags
Cons:
- Harder to manage bug fix releases
Hi. Thanks for the report.
I think that we should start by using some "reference" command as part of towncrier's GHA YAML file.
We currently have this
towncrier/.github/workflows/ci.yml
Lines 161 to 165 in 272993f
but this is called via nox... which makes it a bit harder to read.
One idea is to create a separate composite job for GitHub Actions that can be used as an example for others.
Regarding workflow_dispatch
vs push
and Cons: Harder to manage bug fix releases
can you please add more details about why it's harder to use towncrier for bugfix releases ?
Thanks
One idea is to create a separate composite job for GitHub Actions that can be used as an example for others.
Composite action or reusable workflow? The latter addresses how one can design the triggers, inputs, etc. But the former would still be nice to have as well in order to simplify the execution and export the variables. The action could also handle some of the tagging, but that needs to be discussed with an actual implementation and interface.
For the reusable workflow though, everyone might have different usage, e.g. how to handle the release notes. I think for this case it will be better to document instead and discuss how one would use either workflows, what other tools one can integrate this with, etc.
Design wise, I would say using pipx
would be preferred because it is pre-built and skips the python-setup
action. Although I am not sure if it can integrate with python-setup
if users would prefer to use a specific python environment.
Regarding
workflow_dispatch
vspush
andCons: Harder to manage bug fix releases
can you please add more details about why it's harder to use towncrier for bugfix releases ?
Thanks
I need to get back in the headspace where I was when I wrote that.
- Changelog.md would differ if the bug fixes are cherry-picked on a separate release branch. Getting the Changelog.md back in sync would be tricky there to not have duplication.
But this issue is present for both cases, so I don't think this is what I was considering - One difference between these 2 is where the tag appears.
workflow_dispatch
the tag is after Changelog.md is changed, whilepush
the tag is before that. In the later, the source would not have changes so it might be harder to figure out what are the changes for the specific tag
This is probably what I was thinking of then, but it's not exactly about managing bug fix releases
But the more I think about it the more skeptical I am of on.push.tag
. It would be nice for the maintainers, but is there an actual way of implementing it?
I am not sure what are the problems that you want to solve using towncrier
For CI, you usually want to use the towncrier check
command.
We have the general usage documentation here.
If someting is not clear, we might want to start by improving that documentation.
towncrier check
is executed for every commit, before a merge into the main branch.
Sorry, I was intending to write up an example workflow, which would describe the issue more clearly. This is not about a CI workflow, but a CD workflow, i.e. how to create the tag and/or release using the contents of a .changelog.d
. For example, one CD workflow I have in a project looks like:
.github/workflows/release.yaml
name: 🚀 release
run-name: Release ${{ github.ref_name }}
on:
push:
tags:
- "v[0-9]+.[0-9]+.[0-9]+"
- "v[0-9]+.[0-9]+.[0-9]+-rc[0-9]+"
jobs:
tests:
name: tests
uses: ./.github/workflows/step_test.yaml
build-wheel:
name: build-wheel
needs: [ tests ]
uses: ./.github/workflows/step_build-wheel.yaml
upload_pypi:
name: Upload to PyPI repository
needs: [ tests, build-wheel ]
runs-on: ubuntu-latest
environment:
name: pypi
url: https://pypi.org/project/spglib/
permissions:
id-token: write
steps:
- name: Get sdist
uses: actions/download-artifact@v4
with:
name: Packages
path: dist
- name: Get wheels
uses: actions/download-artifact@v4
with:
pattern: cibw-wheels-*
path: dist
merge-multiple: true
- name: Publish package to PyPI
uses: pypa/gh-action-pypi-publish@release/v1
release:
needs: [ upload_pypi ]
name: Create release
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: softprops/action-gh-release@v1
with:
name: Spglib ${{ github.ref_name }}
draft: true
prerelease: ${{ contains(github.ref, 'rc') }}
generate_release_notes: true
Some example workflows would help figure out how to integrate with this release automation.
The design questions to answer:
- where to put
tonwcrier build
command towncrier
generates theChangelog.md
which would need to be committed in the project, but how would one add this to the workflow
I don't think that towncrier
was designed for this use case.
You might want to check https://docs.openstack.org/reno/latest/ ... I have not used, but from what I remember, you don't need to commit anything. it alwasy keeps all the fragments and always re-generates the release notes
towncrier
was designed to be used in a release process that works something like the one documented here https://towncrier.readthedocs.io/en/latest/release.html
you manually generage the version number, commit the release notes and the push the tag.
I understand, that's why I was showing the 2 workflows to also give the user ideas of how to adapt from 1 to another. The release workflow there is to show-case where a user might be coming from and what they would need to adapt.
There could be 2 approaches here:
- reconfigure the workflow to trigger on dispatch. The problem to be solved there is how to migrate the workflow steps that they might have. I think the example I have would be the minimal complex workflow that would be a steppingstone for users to start from
- keep push on tag, but re-tag commit after the release notes are generated. This can be easily supported in the current workflow by changing the checkout commit/tag to use in subsequent steps. Haven't tested such a workflow though
Feel free to send a PR with what you thing might be useful ... or wait for others to add more feedback to this issue.
I am using a different release process, so I am not very familiar with the problem that is discusses here.