BSK Release Guide

On this page

This guide describes how Basilisk maintainers prepare, validate, and publish major and patch releases. In this guide, a major Basilisk release means a scheduled 2.X.0 feature release, while a patch release means 2.X.Y for Y > 0.

The release workflows contain the ordering and branch decisions. Detailed commands and procedures are collected under Common Release Tasks so the same instructions can be used for both major and patch releases.

Release Model

The version in docs/source/bskVersion.txt, the release tag, and the commit being published must agree. Package versions use PEP 440 syntax without a leading v; Git tags add the leading v.

Basilisk release types

Release type

Source branch

Package version

Tag location

Destination

Major

develop through feature/v2_X_0

2.X.0

master

PyPI

Patch

patch/v2_X_x

2.X.Y

Patch branch

PyPI

Release candidate

Branch being validated

2.X.YrcN

Tested commit

TestPyPI

Pushing a version tag starts the Publish Wheels GitHub Actions workflow. Final tags publish to PyPI, while release-candidate and test* tags publish to TestPyPI.

Release Workflows

Major Release

Use this workflow for a scheduled 2.X.0 release. After publication, finish the workflow by starting the next beta cycle on develop.

Prepare

  1. Create feature/v2_X_0 from develop after all intended release content has been merged.

  2. Finalize the release notes and known issues for 2.X.0.

  3. If a release candidate is required, follow Validate a Release Candidate on the release branch.

  4. Set and verify the final version as 2.X.0.

Validate

  1. Run clean local validation.

  2. Push the release branch and open a PR to develop.

  3. Wait for the Pull Request workflow to pass before merging.

Publish

  1. Merge the release PR into develop.

  2. Merge develop into master.

  3. Create and push the final tag v2.X.0 from master.

  4. Wait for the Publish Wheels workflow to finish and verify the published artifacts.

  5. Create the GitHub Release.

Start the Next Beta Cycle

After the major release is published, prepare develop for the next major release:

  1. Create a beta_X_Y branch from develop for the next planned release.

  2. Set docs/source/bskVersion.txt to the next beta version, such as 2.X.0b0. Do not include a leading v.

  3. Keep the completed release notes under their literal version and date in docs/source/Support/bskReleaseNotes/2.X.rst. Create the next series page if needed and add it at the top of the bskReleaseNotes.rst index. At the top of the next series page, add a Version |release| section containing the active .. include:: ../bskReleaseNotesSnippets/_compiled_latest.rst directive. Move the bsk-release-current label to this section. Keep only one active snippet include in the documentation so notes appear once.

  4. In bskKnownIssues.rst, change the completed release heading to its literal version and create a new Version |release| section above it for the new beta cycle.

  5. Open a PR from the beta branch to develop and wait for CI to pass before merging.

  6. After merging, manually run the Nightly Wheels workflow on develop using workflow_dispatch. Verify that the nightly package index on GitHub Pages contains the new beta version.

Patch Release

Use this workflow for 2.X.Y after v2.X.0 has been published. Only the latest 2.X.Y line is maintained on patch/v2_X_x; current development continues independently on develop.

Prepare

  1. For the first patch in the release line, create patch/v2_X_x from the v2.X.0 tag. For later patches, use the existing patch branch based on the latest v2.X.Y release.

  2. Cherry-pick the approved fixes from develop. Keep each cherry-pick focused and retain the original commit reference.

  3. Finalize the release notes and known issues for 2.X.Y.

  4. If a release candidate is required, follow Validate a Release Candidate on the patch branch.

  5. Set and verify the final version as 2.X.Y.

Validate

  1. Run clean local validation.

  2. Push patch/v2_X_x to origin.

  3. Manually run the Pull Request workflow on patch/v2_X_x and wait for all jobs to pass.

Publish

  1. Create and push the final tag v2.X.Y from patch/v2_X_x.

  2. Wait for the Publish Wheels workflow to finish and verify the published artifacts.

  3. Deploy the patch documentation.

  4. Create the GitHub Release.

Close Out

  1. Confirm that every patch fix also exists on develop. If a fix originated on the patch branch, forward-port it.

  2. Keep patch/v2_X_x available for subsequent patches in the same release line.

Common Release Tasks

Set and Verify the Version

The package version is stored in docs/source/bskVersion.txt and read by pyproject.toml during packaging. Update it manually and use PEP 440 syntax:

Version and tag examples

Build type

Package version

Git tag

Beta

2.X.0bN

No release tag

Release candidate

2.X.YrcN

v2.X.YrcN

Final

2.X.Y

v2.X.Y

Before tagging, confirm that the version file, intended tag, and checked-out commit all describe the same release. Commit every version change before creating its tag.

Finalize the Release Notes and Known Issues

Normal PRs contribute release-note snippets under docs/source/Support/bskReleaseNotesSnippets. Maintainers gather, review, and place the finalized notes in the appropriate version-series RST file; the snippet compiler does not assign notes to releases. At release time:

  1. Compile the current snippets:

    make -C docs release-notes-snippets

  2. Collect and edit the notes for the release. Put them in docs/source/Support/bskReleaseNotes/2.X.rst under a literal version and release date, newest first. For example, 2.12.1 belongs above 2.12.0 in 2.12.rst; 2.13.0 belongs in 2.13.rst. Create a series page and add it to the index when preparing the first release in that series.

  3. Before tagging, sort longer release-note lists into topic subsections within the dated release section. Use the topics below in the same order, omitting empty categories. Small patch releases can remain simple bullet lists.

    • Compatibility and migration

    • Build, installation, and CI

    • Simulation framework and module development

    • Spacecraft dynamics and effectors

    • Environment, gravity, and ephemerides

    • Sensors and flight software

    • MuJoCo and stochastic integration

    • Visualization and data handling

    • Documentation, examples, and validation

    Use RST subsection headings underlined with ~ characters, as in the 2.12.0, 2.11.0, and 2.10.0 notes. Place each entry once under its primary topic, keeping feature-specific examples, documentation, and tests with the feature. Put changes requiring users to adapt their code or setup under Compatibility and migration. Edit for clarity and combine related entries where appropriate, preserving migration instructions, RST references, issue numbers, and beta markers. Sorting and editing are maintainer tasks; PR snippets remain individual bullet entries.

  4. When finalizing the active development version, replace its _compiled_latest.rst include with the finalized bullet content. Leave the include present but commented if useful for the next development cycle. Retain existing section labels and anchors when finalizing a heading so bookmarks continue to work.

  5. Add the release date to the corresponding heading in bskKnownIssues.rst.

  6. Review the notes for duplicate, internal-only, or unclear entries and verify that every RST reference resolves.

  7. Delete only the consumed snippet files. Preserve README.md, the compiler script, the sample, and other underscore-prefixed support files.

For a patch release, create dated 2.X.Y sections for the selected patch notes in bskReleaseNotes/2.X.rst and for the known issues in bskKnownIssues.rst, without disturbing newer develop release content.

Each series page starts with a title followed by its release sections. Use this structure when adding a new series, replacing 2.X with its version series:

Version 2.X Release Notes
========================

.. _bsk-release-current:

Version |release|
-----------------

.. include:: ../bskReleaseNotesSnippets/_compiled_latest.rst

Move the current-release label and active include when advancing to a new series. For another development patch in the same series, add the active section above the finalized releases in the same file. Keep Version 1.x and earlier as the last archive link in the index.

Run Clean Local Validation

Run the validation from the release branch or patch branch being tagged:

python conanfile.py --clean --opNav True --mujoco True
python run_all_test.py
make -C docs clean
make -C docs html SPHINXOPTS="-W --keep-going"

The build, test suite, and documentation build must complete without errors or warnings. See docs/source/Support/User/FAQ.rst for clean-build details and docs/source/Support/Developer/createHtmlDocumentation.rst for documentation prerequisites.

Validate a Release Candidate

Use a release candidate when the wheel pipeline or release payload should be tested through TestPyPI before production publication:

  1. Set bskVersion.txt to 2.X.YrcN and commit the change on the branch being validated.

  2. Run clean local validation and the appropriate GitHub Actions validation workflow.

  3. Tag the tested commit v2.X.YrcN and push the tag. Publish Wheels routes the artifacts to TestPyPI.

  4. Install and validate the TestPyPI artifacts. If changes are required, increment N and repeat with a new commit and tag.

  5. After the candidate passes, set bskVersion.txt to 2.X.Y, commit the final-version change, and repeat local and CI validation before creating the final tag.

Do not move or reuse a release-candidate tag after it has been pushed.

Create and Push a Release Tag

Create the tag on the exact validated commit: master for a major release or patch/v2_X_x for a patch release. Push only after confirming the final version and commit.

git status --short
git tag v2.X.Y
git push origin v2.X.Y

Tag pushes are publication triggers. Treat pushed tags as immutable; if a published version is wrong, correct the problem with a new version rather than moving or reusing the tag.

The Publish Wheels workflow builds all supported wheels and the source distribution. Do not continue until every job succeeds and the expected version is available from PyPI or TestPyPI.

Deploy Patch Documentation

Patch tags do not automatically deploy documentation because the patch branch is neither master nor develop. After publishing a patch:

  1. On the Basilisk Actions page, manually run Merge to master or develop using patch/v2_X_x. This deploys the patch documentation at the site root.

  2. The root deployment replaces the GitHub Pages contents. Run Merge to master or develop again using develop to restore the developer documentation under /develop.

  3. Verify both the root release documentation and the /develop documentation after the workflows finish.

Create the GitHub Release

After package publication succeeds:

  1. Open the repository’s Releases page and select Draft a new release.

  2. Select the published v2.X.Y tag, regardless of which branch contains it.

  3. Set the title to Basilisk v2.X.Y.

  4. Add the release notes manually or use GitHub’s generated notes as a starting point. Remove unresolved RST-only markup such as :ref: roles.

  5. Publish the GitHub Release.

Forward-Port Patch Fixes

Never implement the same fix independently on both the patch branch and develop. Develop it once, then cherry-pick that commit to the other branch. Do not merge develop wholesale into patch/v2_X_x; maintenance branches must remain limited to approved fixes for their release line.

Release Safety Rules

  • Do not create a tag from an uncommitted or unvalidated version change.

  • Do not move or reuse a pushed release tag.

  • Do not merge develop wholesale into a maintenance branch.

  • Keep patch cherry-picks small, focused, and traceable to their original commits.

  • Verify package and documentation publication before announcing a release.