Publishing new releases#
BrianGlobe packages hosted on GitHub have CI workflows setup that are used to automatically upload and publish new version releases when they are made available.
This is the preferred method for publishing new versions to
PyPI (and where appropriate, the linked
conda feedstocks) - avoid manual uploads where possible.
Maintainers can trigger a new release by pushing a new tag, in the format
vX.Y.Z, to the main branch of a package repository.
v prefix is necessary as the workflow will only attempt to upload to
PyPI if the tag matches the format previously provided.
Z values should be integers corresponding to the new version number.
Triggering a new release#
The steps for triggering a new release are:
Head to the “releases” UI on GitHub for the package you want to release a new version for, and select “draft a new release”.
In the “choose a tag” box, opt to create a new tag in the format described above. Ensure that the target is
main(or the desired commit on
mainif the current
HEADis not the desired release state).
Choose the release title. Typically, this is the same as the tag that will be created.
In the “write” box, you should have the option to select the “previous tag”. Choose the tag of the previous release, then select “generate release notes”.
Check the “set as latest release” box.
Then hit “publish release”.
This will trigger a tag-push event to the
main branch, which will set the deployment workflow in motion.
You can now relax whilst the workflow uploads the new package version to
PyPI; however you will need to look out for conda-forge feedstock updates in the next couple of days, or pre-empt this by making your own.
See the section on feedstocks for more information.
On the command line#
If you have an up-to-date clone of the package repository, you can create a release tag on the command line with
git tag vX.Y.Z
or one of
git tag -a vX.Y.Z git tag -a vX.Y.Z -m "Tag annotation message"
if you want to annotate the tag; which is useful for tagging single-commit hotfixes or patches that might come after a release.
Once you have created the tag, you can
git push --tags back to the main repository to trigger the release workflow.
However you still need to create release notes using the GitHub UI as described in the section above.
You will need to select the tag you just pushed, rather than creating a new tag, when you start drafting the release notes.
In the event that the release workflows fails after publishing a release, you will need to:
Delete the tag from the repository from the GitHub tags UI
Delete the release notes and release from the GitHub releases UI
Debug the build failure and the commits with the fix are merged into
Begin the process over again.
A number of BrainGlobe packages are also available through
conda-forge, providing an alternative installation method to
Each package available in this way has a feedstock repository, usually at the GitHub repository:
These feedstocks are linked to their
PyPI counterparts - when a new version comes available on
conda-forge admin bot should open a PR in the feedstock repository which will update the version of the package available through
These PRs must be approved by one of the feedstock maintainers before they are merged in.
Feedstock maintainers and package maintainers may be different
New versions of packages will NOT be available through
condauntil these PRs are merged in.
If the new version changes are extensive or non-trivial; a manual update to the
meta.yaml “recipe” file might be needed, as the admin bot is unable to resolve complex edits.
Examples of such changes are; changing package dependencies, introducing new submodules, and/or editing command-line entry-points.
You will need to use the
conda-forge CI to debug the builds when manually updating in this way.
Workflow for publishing new releases#
BrainGlobe repositories hosted on GitHub each possess a
The basic functionality of these workflows use the neuroinformatics-unit actions to:
Lint the source code
Check the package manifest
Run the package tests
These checks are run against all PRs opened against the repository, and on the
main branch when they are merged in.
When a tag in the
vX.Y.Z format is pushed to
main, these checks are run again and if they are successful the workflow will build the source distribution and upload this to