Add a release process note - #70
Merged
Merged
Conversation
Nothing wrote down how a release is cut. The steps lived in release.sh's closing echo, a comment at the top of publish.yml, and nowhere else, which is enough to follow once and not enough to follow again a year later. RELEASING.md covers the one-time PyPI trusted-publishing setup, the checks worth doing by hand before tagging, the tag and release steps, and what to verify afterwards. Two things it records that are easy to learn the hard way: a version can never be replaced on PyPI, so the artifacts are exercised from a clean environment before the tag is pushed rather than after; and the suite imports the working tree, so it cannot catch a packaging mistake, which is why the built artifacts are installed into throwaway venvs in both install modes. Written without version numbers so it does not go stale.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Nothing wrote down how a release is cut. The steps lived in
release.sh's closingecho, a comment at the top ofpublish.yml, and nowhere else. That is enough to follow once and not enough to follow again a year later, which is roughly the gap between the last two releases.RELEASING.mdat the repository root covers:pypienvironment the publish job declares. Without both, the workflow runs and fails at the upload step../release.shcovers, plus the two checks it does not.Two things it records deliberately
The suite cannot catch a packaging mistake. It imports the working tree, so a missing file or a wrong dependency is invisible to it. The note gives a loop that installs each built artifact into a throwaway venv and draws a chart, in both install modes — a plain install must draw rectangles and refuse
icons=with a message naming the extra, an[icons]install must draw icons. That combination is only observable from a clean environment.A version can never be replaced on PyPI. A file uploaded under a version number is permanent even after deletion, so a mistake means releasing the next patch version. That is the reason the artifact checks belong before the tag is pushed rather than after.
On the content
Written with
X.Y.Zplaceholders and no concrete version numbers, so it does not go stale the way a worked example would. No account names or contact details.Every command in it was run verbatim before committing, including the four-way artifact loop, which passed for wheel and sdist in both modes.
test_documentation.pycollectsdocs/*.md,docs/examples/*.mdandREADME.md, so a root-levelRELEASING.mdis not executed by the suite. Confirmed rather than assumed.MANIFEST.inhasinclude *.md, so it will ship in the sdist alongsideCHANGELOG.md; say the word if you would rather exclude it.