Packaging releases¶
sire
is now (almost) fully tested and deployed using GitHub actions.
The development process should be;
New features are developed on forks or feature branches, called
feature-{feature}
, either in the main sire repository for authorised developers, or in personal forks for new developers.Bug fixes or issue fixes are developed on fix branches, called
fix-issue-{number}
(again in either the main repository or forks).Pull requests are issued from these branches to
devel
. All merge conflicts must be fixed in the branch and all tests must pass before the pull request can be merged intodevel
. NOTE THAT ONLY AUTHORISED DEVELOPERS CAN ACCEPT THE PULL REQUEST. Authorised developers will review the pull request as quickly as they can. They will be greatly helped if the feature is accompanied with tests, examples and/or tutorial instructions.Note that we encourage that new functionality in a pull request is documented, e.g. by adding to the tutorials or writing a detailed description for the website.
The result of this is that devel
should contain the fully-working,
documented and tested code, and most up-to-date version of sire
.
However, this version should not be used for production runs.
Note
The group of developers authorised to have access to the main sire repository and to accept pull requests is not fixed, and will evolve over time. If you wish to join this group then please complete the tutorial and then demostrate your commitment by submitting good issues and pull requests from a personal fork of the repository. Please get in touch if you find this difficult, or follow this workshop and this workshop if you need to learn how to use Git, GitHub, feature branching, merging, pull requests etc.
Defining a release¶
We will release sire
regularly. Releases aim to be backwards
compatible and capable of being used for production runs, at least for
the functionality that is fully described in the tutorial.
Note
It is the job of the release managers (currently chryswoods and lohedges) to decide when it is time to create a new release. If you are interested in helping join the release management group then please feel free to get in touch.
Creating a release¶
There are a number of stages to go through to create a release:
Make sure that all changes have been merged into the
devel
branch, and the GitHub Action has run fully, buildingsire
on all supported platforms, running all the unit tests correctly, and building and uploading the conda packages to thedev
channel on anaconda.org.Next, you should run the full suite of integration tests. These can be found in the sire_bigtests repo. Push a change to this repo, which will trigger a run of all of the integration tests across all supported platforms on GitHub Actions. Make sure that these all pass. If they don’t, then fix any problems and go back to step 1.
On your computer, checkout the
main
branch and then pull in the changes fromdevel
, e.g. using the commandgit pull origin main
. There shouldn’t be any conflicts. If there are, resolve them so thatmain
is identical todevel
.Now update
version.txt
so that it contains the version number for this release.sire
uses a date-based numbering scheme. The version should beYEAR.MAJOR.MINOR
whereYEAR
is the current year,MAJOR
is the number of major release in this year (e.g.2023.3
would be the third major release in2023
) andMINOR
is the patch release for the major release (e.g.2023.3.0
would be the first version of the third major release in2023
, while2023.3.1
would be the first patch release). Minor releases should be used to fix bugs or minor issues with the code. Major releases should be used for new functionality.Now update
doc/source/changelog.rst
with the changelog since the last release. Start the entry with a title that (will) link to the changes on GitHub, e.g. https://github.com/openbiosim/sire/compare/2023.1.0…2023.1.1 links to the changes between the2023.1.0
and2023.1.1
releases. You can change the version numbers in this URL to look at the difference for your versions. Follow a similar format for changes as already exist in this file. Try to link to tutorials that describe new functionality if available.You can now commit your changes and push them to GitHub (e.g.
git commit -a
thengit push
). GitHub Actions will only be triggered on pushes todevel
, so this won’t do anything (yet).Now create a git tag for this release. You can use the command with the format
git tag -a {VERSION} -m "{VERSION} release"
, e.g.git tag -a 2023.1.1 -m "2023.1.1 release"
would be the tag for the2023.1.1
release.Push this tag to GitHub, e.g.
git push --tags
.Now we are finally ready to build the packages. Do this by checking out the
devel
branch (git checkout devel
) and then pulling the changes frommain
intodevel
(git pull origin main
). This will create a merge commit. Accept the commit and then push this back up to GitHub (git push
). This will trigger the GitHub actions that will automatically build and upload all(*) the conda packages.(*) GitHub Actions don’t currently build the ARM64/aarch64 packages. These have to be built and uploaded manually. On a MacOS/M1 or Linux/aarch64 computer you should create build environments for the Python versions that
sire
should support. Activate this environment, and then checkout themain
branch, runpython actions/update_recipe.py
and then runconda-build
via the commandconda build -c conda-forge -c openbiosim/label/dev recipes/sire
. This will result in a conda package in theconda-bld
directory in the root directory of your conda environment. You then need to upload these packages to anaconda.org, e.g. via the commandanaconda --token {PASSWORD} upload --user openbiosim --label main --label dev --force {/path/to/sire-packages}
(modified as appropriate to include the anaconda password and the path to the built conda package).On GitHub, you can now create a release by using the Draft a New Release link. Choose the version number for your release from the tag you created earlier. The text should be simple, e.g. titled
sire {VERSION}
, with the bodyThis is the {VERSION} release of sire.
.Next you should build the docker images for this release. Do this by following the instructions in the containers repository. You should make sure to run the extra command listed there to tag the container with the version number you used earlier.
Finally(!) you can now update the website. To do this, follow the instructions in the website repository.
Bonus! If you are also creating a release of BioSimSpace then you should also follow the instructions in the containers repository to build the notebook container image and instruct try.openbiosim.org to update and use that image.
Super-bonus! If you have time, please write a short news item piece that can be added to the openbiosim website to announce this new release.
(we are in the process of automating many of the above steps, so hope that this process will become much easier in the future)