doc: Github release workflows

[LecrisUT]

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

[adiroiban]

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

	task:
	- name: Check Newsfragment
	run: |
	nox -e check_newsfragment
	nox -e draft_newsfragment >> $GITHUB_STEP_SUMMARY

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

[LecrisUT]

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 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

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, while push 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?

[adiroiban]

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.

[LecrisUT]

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 the Changelog.md which would need to be committed in the project, but how would one add this to the workflow

[adiroiban]

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.

[LecrisUT]

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

[adiroiban]

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.