Publish to PyPI via GitHub CI

[EpicWink]

Removes the package build and publish from the release Nox session, so now it only creates a tag and makes bump/changelog commits.

Adds a package build Nox session called release_build, which optionally checks out a tag (otherwise assumes the tag is already checked out) then builds the distributions.

Adds a publish GitHub CI workflow which will be triggered on release, running release_build and uploading with the publish action.

• Uses trusted publishing, so you'll need to set up the GitHub project environment (name: pypi) and add it to packaging on PyPI. Comments below suggest this environment should be configured to require approvals before running CI workflows.
• I'm assuming git is available, but this should be verified.
• Did you want distribution build to be a separate CI job? That's easy enough to do, but some maintainers I've interacted with prefer the single job. It seems like the lint CI workflow already builds and uploads the distributions. I've merged Split build out from release CI job EpicWink/packaging#1 which does this.
• Does this new CI workflow file need the license comment? The other CI workflow files don't have it.
• Does this merit a CHANGELOG entry?

Resolves #273

[hugovk]

Thanks for the PR :)

[webknjaz]

Looks like there was an agreement to use workflow_dispatch for this. Have you confirmed that people want a delayed upload now instead?

Also, building and running twine check --strict must run continuously to catch possible metadata problems early.

[EpicWink]

Looks like there was an agreement to use workflow_dispatch for this. Have you confirmed that people want a delayed upload now instead?

@webknjaz Brett proposed using workflow_dispatch in #339, I can't find anyone else saying either way. I suggest using release-creation as the trigger as it's tied to a trackable event in GitHub, and doesn't require selecting the target ref (which has potential for mistakes).

Also, building and running twine check --strict must run continuously to catch possible metadata problems early.

Are you suggesting I add --strict to the twine check call in the noxfile? That's a change to the current release process which I don't have knowledge on the impact of.

[webknjaz]

workflow_dispatch doesn't require selecting a ref. I usually have it set up to accept a version as text input. In this scenario, the workflow pushes the tag and not vice versa.

When the tag exists first, various parties would treat it as "release happened". But publishing to PyPI may fail and it would require some tag cleanup. Moreover, many release watchers will remember the old commit a being tagged / versioned.

To solve this, I tend to treat successful upload to PyPI as the point of no return and only push the tag after that.

[webknjaz]

As for twine check, pypi-publish runs it but it's best to run in in PRs — otherwise, releasing may fail at the last minute.

[EpicWink]

workflow_dispatch doesn't require selecting a ref.

GitHub's documentation says it's one of the steps:

5. Select the Branch dropdown menu and click a branch to run the workflow on.

Perhaps main would be the default selected.

---

I usually have it set up to accept a version as text input.

I figure that is as error-prone as entering it at the command line when running nox release. It's similar either way then.

---

In this scenario, the workflow pushes the tag and not vice versa.

When the tag exists first, various parties would treat it as "release happened". But publishing to PyPI may fail and it would require some tag cleanup. Moreover, many release watchers will remember the old commit a being tagged / versioned.

To solve this, I tend to treat successful upload to PyPI as the point of no return and only push the tag after that.

Ahh, I treat tags the opposite way: to me they are just a named commit, but releases must be made from existing tags. I watch for uploads to PyPI, and I'm completely fine with deleting tags. I'm generally pretty wary of writing Git changes in CI.

Honestly, I think it's too limiting to uphold the expectation of "various parties would treat it as "release happened"", as tags are not releases (releases are releases!).

---

As for twine check, pypi-publish runs it but it's best to run in in PRs — otherwise, releasing may fail at the last minute.

Right, so you're saying I should remove it (at least for CI). I disagree, as it's guaranteed to run before attempting upload to PyPI in this proposal, but it's not necessarily guaranteed in PRs (who may edit/skip CI) or locally. I also think it's unnecessary to build the package on every push to every PR, but it may be inconsequential.

To reduce likelihood of trine check failing the release, perhaps I could build and run twine check before pushing the release tag.

[webknjaz]

workflow_dispatch doesn't require selecting a ref.

GitHub's documentation says it's one of the steps:

5. Select the Branch dropdown menu and click a branch to run the workflow on.

Perhaps main would be the default selected.

Yes, it's the default. This is basically for choosing a workflow version from a different branch. Normally, nobody uses it and keeps it as is. But the more important part is being able to define arbitrary inputs.

I usually have it set up to accept a version as text input.

I figure that is as error-prone as entering it at the command line when running nox release. It's similar either way then.

Sort of. You still can build some input validation into the workflow.

In this scenario, the workflow pushes the tag and not vice versa.
When the tag exists first, various parties would treat it as "release happened". But publishing to PyPI may fail and it would require some tag cleanup. Moreover, many release watchers will remember the old commit a being tagged / versioned.
To solve this, I tend to treat successful upload to PyPI as the point of no return and only push the tag after that.

Ahh, I treat tags the opposite way: to me they are just a named commit, but releases must be made from existing tags. I watch for uploads to PyPI, and I'm completely fine with deleting tags. I'm generally pretty wary of writing Git changes in CI.

That's not entirely true. GH Releases can auto-create tags — they don't need to be pre-existing. And their drafts don't even need that.

The problem here is that you control the repo, but you can't influence how external observers work with it. In general, force-pushing tags is a highly discouraged practice, and they are expected to be more or less immutable. Deleting them usually either means an emergency or a supply chain attack.

Honestly, I think it's too limiting to uphold the expectation of "various parties would treat it as "release happened"", as tags are not releases (releases are releases!).

Sure, but I'd be highly suspicious when I see a force-pushed tag after doing a git fetch in an upstream repo.

As for twine check, pypi-publish runs it but it's best to run in in PRs — otherwise, releasing may fail at the last minute.

Right, so you're saying I should remove it (at least for CI). I disagree, as it's guaranteed to run before attempting upload to PyPI in this proposal, but it's not necessarily guaranteed in PRs (who may edit/skip CI) or locally. I also think it's necessary to build the package on every push to every PR, but it may be inconsequential.

To reduce likelihood of trine check failing the release, perhaps I could build and run twine check before pushing the release tag.

That's what I'm saying — python -Im build and twine check --strict dist/* must run in every CI invocation, in every PR and merge. Way before releasing.

[EpicWink]

Failing RTD build due to snowballstem/snowball#229

[EpicWink]

To reduce likelihood of trine check failing the release, perhaps I could build and run twine check before pushing the release tag.

That's what I'm saying — python -Im build and twine check --strict dist/* must run in every CI invocation, in every PR and merge. Way before releasing.

I've made the distribution build and check part of the release nox session, run before creating the Git tag.

---

I don't have familiarity with using the workflow_dispatch GitHub workflows event, and don't feel comfortable switching to that workflow. If you want it, could you please make changes to this PR (or submit a new PR targeting this branch)?

[webknjaz]

I've made the distribution build and check part of the release nox session, run before creating the Git tag.

Does that run in CI, though? This is my main ask.

I don't have familiarity with using the workflow_dispatch GitHub workflows event, and don't feel comfortable switching to that workflow. If you want it, could you please make changes to this PR (or submit a new PR targeting this branch)?

I can look into it, yes. I was also thinking that setting the epoch timestamp for reproducibility would be good as well as producing provenance info via SLSA and GH-native attestations — I normally integrate those too.

[EpicWink]

I've made the distribution build and check part of the release nox session, run before creating the Git tag.

Does that run in CI, though? This is my main ask.

No, but it's a necessary step in the (documented) release process. I've added twine check to the lint CI workflow anyway.

[webknjaz]

It's better to catch any problems before the time of release. This is why I always insist on having the metadata validation a part of the regular CI flow.