Branches and releases - single-cell-data/TileDB-SOMA GitHub Wiki

Things everyone should know

  • Everyone should commit to main as a general rule
  • Micros are tagged on branches such as release-1.5, release-1.6, release-1.7
    • The first will be 1.5.0, 1.6.0, 1.7.0, etc
    • If there are subsequent PRs on a branch we can make a 1.5.1, 1.6.1, etc.
  • When you merge a PR to main, simply add a tag backport release-1.5, backport release-1.6, etc. This will put up a PR for that branch.
  • Timing:
    • Recall major.minor.micro: the minor is the second number and the micro is the third.
    • I know of no scenario which would cause core's major to bump, nor TileDB-SOMA's.
    • Whenever core bumps a minor, dependent packages including TileDB-SOMA bump a minor.
      • Example: core 2.19 appears, TileDB-Py 0.25 is tagged depending on 2.19, TileDB-R 0.23 is tagged depending on 2.19, then a TileDB-SOMA PR can be put up (on main) depending on 2.19, 0.25, and 0.23
      • When core 2.20 appears (along with TileDB-Py 0.26 and TileDB-R 0.24) we will tag a TileDB-SOMA 1.8 -- regardless of how much or how little development work has happened in the TileDB-SOMA repo since 1.7.
    • If it so happens that there is a significant new feature in TileDB-SOMA, we reserve the right to bump the TileDB-SOMA minor even if there hasn't been a core release yet. As of January 2024, this hasn't happened yet, but it could.
    • When core bumps a micro -- e.g. 2.19.0 to 2.19.1 -- we may or may not bump our micro.
      • If the core change doesn't affect TileDB-SOMA at all, we might have no need to bump our micro.

The rest of this document is for the person(s) doing the release.

Roles

  • TileDB-SOMA is an open-source collaboration between TileDB and CZI
  • Most of this checklist, except the Conda and TileDB-Cloud steps, can be done by someone at either company
  • Someone at TileDB needs to be involved to complete the Conda and TileDB-Cloud steps

Incrementing core versions

Example scenario

  • Currently TileDB-SOMA depends on core 2.20 and TileDB-R 0.24.
  • The latest release branch is release-1.8.
  • Now a 2.21 has been released.
  • We need to:
    • Have main depend on 2.21, 0.27, and 0.25
    • Create a release-1.9 branch
    • Ensure that release-1.8 continues to get TileDB-R 0.24 (now that 0.25 is existing)

What needs to be done to make that happen

  • For a PR on the main branch:
  • For a PR on the latest release branch (release-1.8) in this example:
  • After all of this is stable in main, you can make a release-1.9 branch (or whatever version) following the procedure below in this document

What to wait for

If we don't wait for all of those to be true -- if there's some urgency in getting the release out before all R binaries are available -- we need to do things like this:

and then this change will need to be undone in a separate PR a day or two later once all the above binary artifacts are available.

Shortest list

If you've done this a few times before:

  • Discuss with the team
  • Check all backports are in from main to release-i.j
  • Conda-feedstock pre-check PRs for main and py39cloud branches
  • Check for storage space at PyPI
  • Manually run wheel-build and pkgdown actions
  • Make the GitHub release tag with edited release notes
  • Real Conda-feedstock post-tag PRs for main and py39cloud branches
  • TileDB-internal notebook-image and UDF-image PRs
  • Request deployment to cloud

The rest of this document is a spell-out of these essential steps.

Deciding on a release

  • Post in the common Slack channel that you want to do a release
    • Include a list of the PRs that will be in the release — the GitHub UI lets you auto-generate this list
    • Wait for two people to agree
  • Validate the version number and wait for two people to agree
    • We use semantic versioning which is seemingly unambiguous: majors for backward-incompatible changes, minors for new features that are backward-compatible, micros for bugfixes
    • But in reality this is subjective: for example, if something was a bit incomplete before, was its incompleteness a bug being fixed, or is the new bit a new feature?
    • Be sure to also bump the tiledbsoma version at apis/r/DESCRIPTION, as this lives outside of GitHub versioning
  • Considering the scope of changes in the release, a release candidate (e.g. i.j.krc0, with no - before rc0, for PEP386) might be required if:
    • If new dependencies, end-to-end validation is required
    • If new features are introduced, validation of features is required
    • If there are removals of APIs, validation of downstream software is required
    • If there are deprecations, proper release notes with explanations and replacements outlines is required
    • If a release candidate was created, all validations must be completed and successful to cut the release

Validating

  • CI in the TileDB-SOMA repo is our #1 signal
  • Conda CI (below)
  • Notebook evaluations
    • At first, manually evaluate them
    • Over time: automate notebook-evaluations in a CI job

Branch/tag mechanics

Make the new release branch

  • For each minor (i.j++.0) make a branch release-i.j but don’t make a tag yet. If we need to backport bugfixes from main later, we’ll be glad we had this. Also we’ll need this just below.

  • The moment you make a new release branch like release-1.8, also make a new label like backport release-1.8 -- this will allow the backport bot (discussed above) to work

  • Copy the GitHub branch-protection rules from main to the new branch

R main-branch version

After a new release-i.j branch has been created, put up a PR on main setting apis/r/DESCRIPTION version to i.j.99: for example https://github.com/single-cell-data/TileDB-SOMA/pull/2005. Subsequent commits on main will be i.j.99.1, i.j.99.2, etc.

Readthedocs

  • Visually/manually audit https://tiledbsoma.readthedocs.io/en/latest/ (note the latest bit -- this is main) to be sure any new classes/methods/etc are present. There is a a crucial technical compromise as detailed on https://github.com/single-cell-data/TileDB-SOMA/pull/3284. It is not sufficient to only commit Python code and let readthedocs auto-generate -- manual curation is necessary. Check this before the release.
  • Have a release-i.j in readthedocs, Active, but Hidden --- check this as well as this should be the docs for the version you're about to tag

CZI acceptance tests

As soon as there's a stable commit hash of main with all dependent packages updated -- but without waiting for the TileDB-SOMA tag -- loop in CZI for acceptance tests. They may find bugs needing fixing before we do the TileDB-SOMA tag.

  • Python census-reader acceptance
  • R census-reader acceptance
  • Python-only census-builder acceptance

somacore Conda-feedstock check

It's possible that in our apis/python/setup.py and .pre-commit-config.yaml we've bumped a somacore version but not the associated Conda feedstock

tiledbsoma Conda-feedstock pre-check PR

Before publishing a particular Git tag somewhere on the branch, put up a pair of PRs on the feedstock repo with the SHA of the commit you would be tagging.

Please follow the instructions about Conda and feedstock PRs.

R release-branch version

Immediately before publishing a particular Git tag somewhere on the branch, put up a PR on this repo bumping the package version in apis/r/DESCRTIPTION and apis/r/NEWS.md, as the R package gets its version not from the GitHub tag

PyPI storage-space check

GitHub RC tag and/or manual job runs

Same as next step, but, for i.j.0 releases, always do a i.j.0rc0 first (note: no - before rc0, for PEP386)

  • Too much can change in the dependency chain
  • It's possible for PyPI wheel-builds to fail immediately post-tag, requiring you to have to immediately turn around and do an i.j.1. Use the rc to avoid this.
  • But if you manually run the sdist & wheels job and the pkgdown job, that's really all the rc tag is important for, and those two would suffice -- and the fewewr RC tags we publish, the less disk space we take up at PyPI

Wheels check

Go to https://github.com/single-cell-data/TileDB-SOMA/actions and do a manual run of the "sdist & wheels" on the branch you're intending to tag -- unless the previous nightly was successful. If it wasn't, absolutely do this first before continuing, since if you don't, PyPI publish will fail later on. If you did an RC tag then you needn't do this, as the RC tag will run the wheels-build -- but do check GitHub Actions status for all-green.

GitHub release tag

Publish a git tag and GitHub release, trigger CI to build, and publish PyPI packages.

r-universe

Update https://tiledb-inc.r-universe.dev/tiledb

cellxgene-census update

Put up a PR on cellxgene_census to have it depend on the new TileDB-SOMA version

  • Without this, any Python user/system that installs both tiledbsoma and cellxgene_census will get the older version not the newer

tiledbsoma Conda-feedstock PR

Please follow the instructions about Conda and feedstock PRs.

TileDB-internal Docker-image repos

See the internal Notion document for mechanics.

Notifications

Notify the TileDB Cloud team in their internal Slack channel that new versions are forthcoming and indicate whether or not the deployment needs to be prioritized for a customer/prospect.

Post release notifications in:

  • The cross-company Slack channel
  • The #release-coordination channel
  • Customer channels

Artifacts

Note that all Conda artifacts for dependent packages must be present in order to Conda-ify TileDB-SOMA.

Aside for arm64 (M1/M2) Macs

  • As noted on https://github.com/single-cell-data/TileDB-SOMA/pull/1385, using GitHub Actions as of mid-2023 the best we can do for MacOS arm64 is to cross-compile for arm64 while actually running on x86_64.
  • This is tracked here: https://github.com/github/roadmap/issues/528 -- TL;DR maybe 2023Q4 GHA will have this available
  • This also means we can build the arm64 wheels in CI but we cannot smoke-test them -- since we do not have arm64 hardware to run the smoke test on
    • Consolation prize:
    • Get the artifacts from the CI job
    • Download and unzip wheels-macos-arm64.zip
    • pip install tiledbsoma-i.j.k-cp311-cp311-macosx_11_0_arm64.whl (or whatever your OS version)
    • In Python, import tiledbsoma and tiledbsoma.show_package_versions()
    • Run unit tests via python -m pytest apis/python/tests

Bug-fix branches

Problem to solve:

  • TileDB-SOMA 2.n exists, depending on core 2.m et al.
  • We need to bug-fix TileDB-SOMA 2.(n-1), which depends on core 2.(m-1) et al.
  • The R DESCRIPTION-file syntax does not support upper bounds, so any codemod pushed to a non-latest branch will result in the PR on TileDB-SOMA 2.(n-1) getting a version of TileDB-R for core 2.m, unless we explicitly force it not to.
  • Discussion: https://github.com/single-cell-data/TileDB-SOMA/pull/1993#issuecomment-1881150316
  • Solution examples:
    • #1972 pins TileDB-R to 0.21 for the release-1.5 branch
    • #1996 pins TileDB-R to 0.22 for the release-1.6 branch