Implement RFC #76: amaranth-boards versioning policy.

[fischermoseley]

This PR implements RFC 73 and adds a versioning policy to amaranth-boards. A few quick notes about this PR:

1. The package and release steps are borrowed from the main repo's CI configuration, and I've thrown in a bash step that will automatically tag the HEAD before generating the Python package.

2. The tagging logic will throw an error if there's no existing tags in the repository. As a result, we may need a v0.0.0 tag to be made on HEAD before this PR is merged - that'd make v0.0.1 be the first release published to PyPI.

3. I made a few commits in my fork to convince myself (and maintainers!) that the tagging logic was working correctly, but these extra commits needn't make their way upstream. Let's definitely squash these commits before merging. Unfortunately I wasn't able to test that the pushes to PyPI and releases to GitHub work, but since that part of the workflow is the same as what's on the main repo it seems low-risk.

[whitequark]

Thanks! Let's see it work...

[whitequark]

It didn't: https://github.com/amaranth-lang/amaranth-boards/actions/runs/22083941628/job/63814605510

[fischermoseley]

Darn - the permissions issue it fails with matches something I ran into during testing on my forked repo. I had to enable read/write permissions on the repo from within the GitHub Actions settings (Settings -> Actions -> General -> Workflow Permissions).

There might be a more granular way to enable that from within the YAML, but I'd have to go digging as GitHub Actions permissions are still a bit of a mystery to me...

[whitequark]

It should be enabled:

[fischermoseley]

Actually - upon further inspection it looks like it's failing to find an existing tag to increment. Perhaps tagging a commit behind d1133be as v0.0.0 and re-running CI would do the trick?

[whitequark]

Pushed the tag!

[whitequark]

This seems to have succeeded: https://github.com/amaranth-lang/amaranth-boards/actions/runs/22084202136/job/63815701838

... but there's no actual release?? https://pypi.org/project/amaranth-boards/0/#history

[fischermoseley]

It seems to exist in PyPI if you click the Download Files button - there's a .whl in there that was updated a few minutes ago. But perhaps it considers versions 0.0.0 and 0 to be equivalent, and therefore doesn't consider it a new release?

[whitequark]

Oh, makes sense.

[whitequark]

I've pushed an empty commit to main.

[whitequark]

I haven't the faintest clue what this means: https://github.com/amaranth-lang/amaranth-boards/actions/runs/22084613447/job/63816964770#step:7:126

[fischermoseley]

I suppose we could retry with --verbose like it suggests? The best documentation I could find was this issue. It doesn't look like we're running into the same issue as they did, but one of the maintainers said that --verbose will expose the twine output, which was useful to them at least.

Sorry that this is being a bit of a pain, the effort's much appreciated!

[whitequark]

https://github.com/amaranth-lang/amaranth-boards/actions/runs/22085054959/job/63817923871#step:7:160

[fischermoseley]

I think this might be due to moving the tagging step to after the build and metadata check. Since the tag hasn't been made at the time of build, PDM thinks that the build is dirty and names it appropriately, causing twine to reject it during the upload.

We could definitely build twice but that seems wasteful - how about we make the tag first, and then only push the tag if the metadata check succeeds (or even after the PyPI release succeeds)? I can definitely type up another PR with that change if you'd like.

[whitequark]

or even after the PyPI release succeeds

This seems reasonable yeah.

[fischermoseley]

Just pushed the change here:
fischermoseley@8996aa9

[whitequark]

Pushed to main!

[fischermoseley]

Looks like that pushed to TestPyPI successfully! It did skip pushing to production PyPI and making the release on GitHub, which should be fixed in the commit below:

fischermoseley@fcb7cb2

Sorry again for all the trouble!

[fischermoseley]

Thanks for the pull! It looks like it's now failing the release to PyPI with:

Error: Attestation generation failure: The following distributions already have publish attestations: * /github/workspace/dist/amaranth_boards-0.0.4.tar.gz -> /github/workspace/dist/amaranth_boards-0.0.4.tar.gz.publish.attestation
* /github/workspace/dist/amaranth_boards-0.0.4-py3-none-any.whl -> /github/workspace/dist/amaranth_boards-0.0.4-py3-none-any.whl.publish.attestation

I'm guessing this is because the release to TestPyPI also generated these attestations, and didn't clean them up afterwards. I see a few options, we could:

1. Modify the workflow logic so that we don't release to TestPyPI and PyPI at the same time.
2. Delete the attestations between the release to TestPyPI and PyPI.
3. Don't bother releasing to TestPyPI at all.

Any thoughts on what direction to take?

[whitequark]

3. Don't bother releasing to TestPyPI at all.

If we're going to release to PyPI on every commit I don't really see any point in bothering with Test PyPI.

[fischermoseley]

Sounds good to me - we should be good to just comment out that step in the publish-package job. I tossed another commit on my fork, but feel free to make the change yourself if that's easier :)

[whitequark]

I'm actually quite happy to do cherry-picks as I've been doing mostly other stuff in parallel.

[whitequark]

This is definitely broken...

[fischermoseley]

Indeed - perhaps we delete that release once the CI is stable. I did toss another commit down that should fix that - it exports the version during tag creation, and then uses it later on when making the release.

[whitequark]

Done!

[fischermoseley]

That seems to have worked! PyPI looks good, as do the tags and releases on GitHub. I think we can declare victory!

[whitequark]

🎉 Thanks for your effort in making this happen, it is very much appreciated!