Improve release instructions

[JelleZijlstra]

This is what I've actually been doing, but better to document it.

[JelleZijlstra]

cc @AA-Turner since I think you wrote the current version of these instructions

[hauntsaninja]

Looks good, feel free to merge or wait for AA-Turner :-)

[hauntsaninja]

nit: for releases I personally find it helpful to split up steps as much as possible and not use and

[AA-Turner]

I think here it is fine as the step is "update the version number", there are just two places to do it.

A

[hauntsaninja]

Might be nice to write out the commands for testing local builds

[JelleZijlstra]

I tend to just install it and import it... I'd rather leave this out for now in the hope that we'll switch to fully automatic releases.

[AA-Turner]

I think this is fine for better release instructions.

I've started to prefer release automation -- either fully automated release on PR merge, or automatic release on pushing a tag. If there would be interest in this I could mock up a GHA script?

A

[JelleZijlstra]

Thanks for the reviews! I'd also prefer automatic releases, since I don't exactly trust myself to do it right. (It's a lot easier with build than it was before, though.) On Black and a couple of other projects I maintain we generate releases automatically on tags, which works well. Could you tell me more about the option to release on PR merge? I haven't seen that before.

[AA-Turner]

Could you tell me more about the option to release on PR merge?

The idea is entirely stolen from Hypothesis, although that project may have stolen it from somewhere else.

The precis is that each PR includes a changelog fragment file (RELEASE.rst or similar), which is detected by CI and used to bump the version (major/micro/patch), prepend to the changelog, and build/tag/release.

The versioning information comes from the marker file -- either a line with release level, or release level in the suffix (RELEASE.minor.md).

I have an implementation for another project that I'm happy to adapt for here -- the issue is testing, really, as you don't want to be releasing thousands of versions whilst tweaking the infrastructure. Test PyPI might be a good solution for this, though.

A