Publishing a Release
This guide is specific to contributors and serves to document how we publish releases of the offchain library. It might be an interesting read, but you'll likely never use anything out of it on a day-to-day basis.
Prerequisites
There is a bit of polish that needs to be done before pushing your code.
Knowing your Version
Before merging your pull request, you'll want to make sure that the application version defined in pyproject.toml
has been incremented, following semantic versioning. This will be used later when tagging the release and in the changelog.
If we're currently on version 0.0.1
, and this pull request is a patch release, we'll update our version
to 0.0.2
.
Create a Changelog Entry
You'll want to ensure you've written a version entry to the changelog. This will not only be published in the docs, but it will be extracted and written as the description for the release.
Entries are formatted like:
# Changelog
## v0.0.2
- element
- another element
- the best element
## v0.0.1
- worst element
- another solid element
- the sad element
Tip
Make sure the changelog file has a new line at the end.
You can add as many elements as you'd like, but make sure the versions are separated by new lines in descending order and are appended with a v
like shown in the above example.
Update the Index Version
You'll also want to update the version that's notated on the index page.
Similarly to how the changelog version is formatted, make sure the version is appended with a v
.
Once you've confirmed the version is correct, your changelog entry has been committed, and you have approval on
your pull request, merge it into main
to begin the next steps.
Tag a Release
Now that your changes are merged into main
, we can now tag this release and configure it on GitHub.
When running the command below, this will create a tag for v0.0.2
and sign it using your GPG key.
Make sure your versions are appended with v
. This will be the version published to PyPi later.
Warning
All releases must be made with a GPG signed tag. Don't create a tag without signing it.
When pushing the tag, the CI pipeline will validate that your tag matches the version defined in pyproject.toml
.
If it doesn't, the version will automatically update to match the tag version. This is only for safety and should never happen.
If the versions match and are good to go, a release branch will be created, including the commits from the tag.
Publish the Release on GitHub
Once you've created and pushed the tag, you should notice a draft release on GitHub. The title should be v0.0.2
,
and the content should be from the changelog for that release.
Success
Validate that everything is correct and publish the release! This will automatically publish the release to PyPi.
And you're done, congratulations! You've successfully published a new version of the offchain library!