From f9cc2545fa0f3d1b25525646790bca73f48cccaf Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Wed, 8 Oct 2025 12:00:00 -0600 Subject: [PATCH 01/15] Move existing Install instructions to Build --- README.md | 2 +- docs/source/Build.rst | 16 ++++++++++++++++ docs/source/{Install => Build}/External.zip | Bin .../{Install => Build}/buildExtModules.rst | 4 +--- docs/source/{Install => Build}/customPython.rst | 0 docs/source/{Install => Build}/installBuild.rst | 0 .../{Install => Build}/installBuildConan.rst | 0 .../{Install => Build}/installOnLinux.rst | 0 .../{Install => Build}/installOnMacOS.rst | 0 .../{Install => Build}/installOnWindows.rst | 0 docs/source/{Install => Build}/pipInstall.rst | 0 docs/source/{Install => Build}/pullCloneBSK.rst | 0 docs/source/Install.rst | 10 ---------- docs/source/index.rst | 2 ++ 14 files changed, 20 insertions(+), 14 deletions(-) create mode 100644 docs/source/Build.rst rename docs/source/{Install => Build}/External.zip (100%) rename docs/source/{Install => Build}/buildExtModules.rst (99%) rename docs/source/{Install => Build}/customPython.rst (100%) rename docs/source/{Install => Build}/installBuild.rst (100%) rename docs/source/{Install => Build}/installBuildConan.rst (100%) rename docs/source/{Install => Build}/installOnLinux.rst (100%) rename docs/source/{Install => Build}/installOnMacOS.rst (100%) rename docs/source/{Install => Build}/installOnWindows.rst (100%) rename docs/source/{Install => Build}/pipInstall.rst (100%) rename docs/source/{Install => Build}/pullCloneBSK.rst (100%) diff --git a/README.md b/README.md index 1eb0af452a..3bf96456de 100644 --- a/README.md +++ b/README.md @@ -39,7 +39,7 @@ Now, when you want to use a tutorial, navigate inside that folder, and edit and Any new BSK module development should not occur within the BSK folder as this will be updated rapidly. Rather, new FSW algorithm or simulation code modules should be created in a custom folder outside of the BSK directory. -See the [building custom modules](docs/source/Install/buildExtModules.rst) web page +See the [building custom modules](docs/source/Build/buildExtModules.rst) web page for more information. To use the standalone 3D Visualization, download the [Vizard](docs/source/Vizard/VizardDownload.rst). diff --git a/docs/source/Build.rst b/docs/source/Build.rst new file mode 100644 index 0000000000..7974387389 --- /dev/null +++ b/docs/source/Build.rst @@ -0,0 +1,16 @@ +Build +===== + +.. toctree:: + :maxdepth: 1 + :caption: Contents: + + Build/customPython + Build/pullCloneBSK + Build/installOnLinux + Build/installOnMacOS + Build/installOnWindows + Build/installBuild + Build/buildExtModules + Build/installBuildConan + Build/pipInstall diff --git a/docs/source/Install/External.zip b/docs/source/Build/External.zip similarity index 100% rename from docs/source/Install/External.zip rename to docs/source/Build/External.zip diff --git a/docs/source/Install/buildExtModules.rst b/docs/source/Build/buildExtModules.rst similarity index 99% rename from docs/source/Install/buildExtModules.rst rename to docs/source/Build/buildExtModules.rst index de49ae009f..8ee2874375 100644 --- a/docs/source/Install/buildExtModules.rst +++ b/docs/source/Build/buildExtModules.rst @@ -11,7 +11,7 @@ Motivation ---------- .. sidebar:: Source Code - An example external folder with custom Basilisk modules and message definitions can be downloaded :download:`here `. + An example external folder with custom Basilisk modules and message definitions can be downloaded :download:`here `. It is preferred that the user not put their own modules inside the official Basilisk folder unless this module is intended to be pushed back to the repository. This keeps the official Basilisk folder free from local customizations and thus easier to keep up to date. With Basilisk 2.0 and onwards the user has the ability to create modules which are not included in basilisk repository. The new build system allows a single folder containing custom BSK modules to be included into a single Basilisk build. This document outlines how this is done. The resulting build product will contain both the official Basilisk modules as well as modules available within this external folder. @@ -70,5 +70,3 @@ Frequently Asked Questions - The custom Basilisk modules are built into a ``Basilisk.ExternalModules`` package. For example, to load a module called ``customCppModule``, use:: from Basilisk.ExternalModules import customCppModule - - diff --git a/docs/source/Install/customPython.rst b/docs/source/Build/customPython.rst similarity index 100% rename from docs/source/Install/customPython.rst rename to docs/source/Build/customPython.rst diff --git a/docs/source/Install/installBuild.rst b/docs/source/Build/installBuild.rst similarity index 100% rename from docs/source/Install/installBuild.rst rename to docs/source/Build/installBuild.rst diff --git a/docs/source/Install/installBuildConan.rst b/docs/source/Build/installBuildConan.rst similarity index 100% rename from docs/source/Install/installBuildConan.rst rename to docs/source/Build/installBuildConan.rst diff --git a/docs/source/Install/installOnLinux.rst b/docs/source/Build/installOnLinux.rst similarity index 100% rename from docs/source/Install/installOnLinux.rst rename to docs/source/Build/installOnLinux.rst diff --git a/docs/source/Install/installOnMacOS.rst b/docs/source/Build/installOnMacOS.rst similarity index 100% rename from docs/source/Install/installOnMacOS.rst rename to docs/source/Build/installOnMacOS.rst diff --git a/docs/source/Install/installOnWindows.rst b/docs/source/Build/installOnWindows.rst similarity index 100% rename from docs/source/Install/installOnWindows.rst rename to docs/source/Build/installOnWindows.rst diff --git a/docs/source/Install/pipInstall.rst b/docs/source/Build/pipInstall.rst similarity index 100% rename from docs/source/Install/pipInstall.rst rename to docs/source/Build/pipInstall.rst diff --git a/docs/source/Install/pullCloneBSK.rst b/docs/source/Build/pullCloneBSK.rst similarity index 100% rename from docs/source/Install/pullCloneBSK.rst rename to docs/source/Build/pullCloneBSK.rst diff --git a/docs/source/Install.rst b/docs/source/Install.rst index c91febc6fd..9509cb76db 100644 --- a/docs/source/Install.rst +++ b/docs/source/Install.rst @@ -11,13 +11,3 @@ Install .. toctree:: :maxdepth: 1 :caption: Contents: - - Install/pullCloneBSK - Install/installOnLinux - Install/installOnMacOS - Install/installOnWindows - Install/installBuild - Install/buildExtModules - Install/customPython - Install/installBuildConan - Install/pipInstall diff --git a/docs/source/index.rst b/docs/source/index.rst index 2395588f08..aa3f924859 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -200,8 +200,10 @@ Related Publications .. toctree:: :maxdepth: 1 :caption: Basilisk: + :includehidden: Install + Build Learn Support Documentation/index From 258d672968a2f5aefecef5fdef0f4cb2662a785f Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Wed, 8 Oct 2025 12:00:00 -0600 Subject: [PATCH 02/15] Add new pip install instructions --- .gitignore | 4 +++ docs/source/Build.rst | 18 ++++++++-- docs/source/Install.rst | 74 ++++++++++++++++++++++++++++++++++++----- docs/source/index.rst | 2 +- 4 files changed, 86 insertions(+), 12 deletions(-) diff --git a/.gitignore b/.gitignore index 50fec285af..b97b1508a8 100755 --- a/.gitignore +++ b/.gitignore @@ -65,4 +65,8 @@ lib/* build/ !.github/actions/build/ !.github/actions/build/** + +# Documentation +!docs/source/Build/ + *.git-template diff --git a/docs/source/Build.rst b/docs/source/Build.rst index 7974387389..171f852cae 100644 --- a/docs/source/Build.rst +++ b/docs/source/Build.rst @@ -1,16 +1,28 @@ -Build -===== +Building from Source +==================== + +.. _bskInstall-build: + +For advanced users and developers who want to customize or debug Basilisk. For +most users the precompiled version available on PyPI is sufficient. See the +:ref:`Install Instructions ` for more information. + +.. note:: + To use custom C++ modules, Basilisk must be built from source. + The prebuilt PyPI wheels are designed for most users and include all standard + features, but they do not yet support linking external C++ modules. + We're actively exploring ways to enable this in future releases. .. toctree:: :maxdepth: 1 :caption: Contents: - Build/customPython Build/pullCloneBSK Build/installOnLinux Build/installOnMacOS Build/installOnWindows Build/installBuild Build/buildExtModules + Build/customPython Build/installBuildConan Build/pipInstall diff --git a/docs/source/Install.rst b/docs/source/Install.rst index 9509cb76db..4b56d45bba 100644 --- a/docs/source/Install.rst +++ b/docs/source/Install.rst @@ -1,13 +1,71 @@ -.. Basilisk documentation master file, created by - sphinx-quickstart on Mon Sep 23 13:52:19 2019. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - .. _bskInstall: Install ======= -.. toctree:: - :maxdepth: 1 - :caption: Contents: +Basilisk can be installed either from `PyPI `_ as +a prebuilt wheel or built locally from source. +The prebuilt wheels include all build options, such as optical navigation +and MuJoCo dynamics, but do **not** support linking external C++ modules, as +this requires rebuilding Basilisk. + +If you want to use custom C++ modules, or prefer smaller install sizes by +excluding unused features, you must build Basilisk from source. +See the :ref:`Building from Source ` for more information. + +.. note:: + We are currently investigating ways to allow users to link external C++ + modules while using the prebuilt PyPI wheel. Stay tuned! + + +The easiest way to install Basilisk is using ``pip`` to install the prebuilt +package from PyPI. Run: + +.. code-block:: bash + + pip install bsk + +Or, if using `uv `_ (a modern Python package manager): + +.. code-block:: bash + + uv pip install bsk + +This installs the latest stable version of Basilisk and all dependencies. +To install a specific version, run: + +.. code-block:: bash + + pip install bsk== + +Replace ```` with the desired release number, e.g. ``2.0.0``. + + +**Prebuilt wheel availability:** + +- **Windows:** Windows 10/11 (x86_64) +- **macOS:** macOS 11+ (x86_64 and Apple Silicon arm64) +- **Linux:** Manylinux 2.24+ (x86_64, aarch64) + +All wheels are built as **ABI3** packages for Basilisk supported Python +versions. + +.. note:: + On unsupported systems or Python versions, ``pip`` will automatically + download the source archive (``.tar.gz``) and build Basilisk locally. + This requires a C++ compiler toolchain and standard build tools + to be installed on your system. + +To keep the wheel size smaller, the large BSK data files are not installed by +default. If the user wants to use script that assumes they are included into +the Basilisk python package, then go to the command line, change the current +directory to be inside the environment where Basilisk was ``pip`` installed, +and run the command:: + + bskLargeData + +This command runs a python file stored in the ``src/utilities`` folder. +The ``pip install`` process automatically +creates this console command in the current python environment to call this +python file. The file directly downloads the missing large BSK data files and put +them into the local Basilisk python package installation. diff --git a/docs/source/index.rst b/docs/source/index.rst index aa3f924859..9b31ffb97a 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -203,7 +203,7 @@ Related Publications :includehidden: Install - Build + Building from Source Learn Support Documentation/index From fa9eed49e23643cb7098c4a2ea8b2fc5f079c074 Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Wed, 8 Oct 2025 14:56:22 -0600 Subject: [PATCH 03/15] Update README.md with install guide --- README.md | 45 ++++++++++++++++++++++++++++++++++----------- 1 file changed, 34 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 3bf96456de..1f2faa25dc 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,56 @@ # README -### Basilisk +## Basilisk * [Summary of Basilisk](docs/source/index.rst) * [Release Notes](docs/source/Support/bskReleaseNotes.rst) -### How do I get set up? -The following links contain installation instructions for the supported platforms: +### Installation -- [Setup a macOS Development Environment](docs/source/Install/installOnMacOS.rst) +Basilisk can be installed in two ways, either from PyPI or by building from +source. -- [Setup a Linux Development Environment](docs/source/Install/installOnLinux.rst) +For most users, installing from PyPI is the easiest and fastest way to get +started. Building from source is recommended if you need to link to external +C++ modules or want to customize the build configuration. -- [Setup a Windows Development Environment](docs/source/Install/installOnWindows.rst) +#### Install from PyPI +The easiest way to get started with Basilisk is to install the prebuilt wheel +from [PyPI](https://pypi.org/project/bsk/): +```bash +pip install bsk +``` + +This installs the latest stable version with all standard features +(e.g. optical navigation and MuJoCo). See the [install](docs/source/Install.rst) +docs for supported platforms and additional details about the wheels. + +#### Build from Source + +If you need to use external C++ modules or want to customize the build, follow +the platform-specific setup instructions: + +* [Setup a macOS Development Environment](docs/source/Build/installOnMacOS.rst) + +* [Setup a Linux Development Environment](docs/source/Build/installOnLinux.rst) + +* [Setup a Windows Development Environment](docs/source/Build/installOnWindows.rst) + +See the [Build from Source docs](docs/source/Build.rst) for full details. ### Basilisk Development guidelines * [Contributing](CONTRIBUTING.md) * [Coding Guidelines](docs/source/Support/Developer/CodingGuidlines.rst) - ### Getting Started + To get started with Basilisk (BSK), several tutorial python files are provided in the installed package. Within this -web page documentation site, they are listed and discussed in the [integrated example script](docs/source/examples/index.rst) -page. The -documentation lists the scenarios in an order that facilitates learning basic BSK features. The python scripts +web page documentation site, they are listed and discussed in the [integrated example script](docs/source/examples/index.rst) page. + +The documentation lists the scenarios in an order that facilitates learning basic BSK features. The python scripts are stored under `basilisk/examples`. A good start would be to run `scenarioBasicOrbit.py`. To play with the tutorials, it is suggested the user makes a copy of these tutorial files, and use the copies in order @@ -45,7 +69,6 @@ for more information. To use the standalone 3D Visualization, download the [Vizard](docs/source/Vizard/VizardDownload.rst). This is in development, but does provide a 3D view of many of the simulation states. - ### Who do I talk to? Questions and answers are fielded in the project's [Github Discussions](https://github.com/AVSLab/basilisk/discussions). From 1203562fda7f845277ffa5fd5c558f684ec99b02 Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Mon, 13 Oct 2025 09:07:13 -0600 Subject: [PATCH 04/15] Minor tweaks to wheel instructions --- docs/source/Build/pipInstall.rst | 72 +++++++------------------------- 1 file changed, 14 insertions(+), 58 deletions(-) diff --git a/docs/source/Build/pipInstall.rst b/docs/source/Build/pipInstall.rst index 9496a7be84..0119246a56 100644 --- a/docs/source/Build/pipInstall.rst +++ b/docs/source/Build/pipInstall.rst @@ -3,22 +3,18 @@ .. _pipInstall: -Advanced: Building and Installing Pre-Compiled Basilisk Wheels -============================================================== +Advanced: Building Pre-Compiled Basilisk Wheels +=============================================== -.. warning:: - - :beta:`Pip Wheel Support` This method of building Basilisk is currently a beta feature, and should only be attempted by advanced users - familiar with `Python packaging and distribution - `_. - This method is not yet guaranteed to work on every platform, and there are still some annoyances - to iron out, but we appreciate any feedback you may have. +The following instructions explain how to build wheels with Basilisk. +While we distribute pre-compiled wheels already in :ref:`bskInstall`, +you can also build them manually using the steps below. This is desirable if +you want to use Python wheels but still need to enable custom build options +or link against a custom external module location. - Most users should see :ref:`configureBuild` for documentation on the regular build process. - -Building and Installing with ``pip`` ------------------------------------- +Building Wheels and Installing with ``pip`` +------------------------------------------- .. note:: @@ -44,16 +40,10 @@ Build options (as passed to ``conanfile.py`` and described in :ref:`configureBui installations (``pip install -e .``) are not currently supported. Please follow the standard :ref:`configureBuild` process. -After installing Building Basilisk ``wheel`` File -------------------------------- -On its own, there is no significant benefit to installing Basilisk in this way. However, supporting standard Python -packaging tools means that Basilisk can now be built into a pre-compiled `"wheel" (.whl) file -`_ that can be shared -and installed on other compatible machines. - Using ``pip``, the command below will generate a ``Basilisk-*.whl`` file in the current directory:: pip wheel --no-deps -v . @@ -100,29 +90,6 @@ The following command is used to both download the code and compile Basilisk wit pip install git+https://github.com/AVSLab/basilisk.git -Wheel Compatibility -------------------- - -.. warning:: - - Wheel compatibility is currently being verified across Python versions and different platforms. So far, - some users have reported successfully installing the same wheel on different Ubuntu versions and with - different Python versions, but your mileage may vary. - - If you choose to try this feature and run into and problems, please `raise an issue - `_ for the Basilisk maintainers to investigate. - -When installed using a standard Python packaging tool such as ``pip``, Basilisk will automatically be -built using the `Python Limited C API `_. The -resulting wheel file will contain a set of compiled Python extension modules that, at least in theory, can be -run using any compatible Python version (currently, any from Python 3.8 to 3.11). - -To maintain backwards compatibility, standard Basilisk installations via ``python conanfile.py`` are not -compatible between different Python versions, as is stated in :ref:`customPython`. However, users can -also forcibly build with the Python Limited C API by providing the ``--pyLimitedAPI`` flag:: - - python conanfile.py --pyLimitedAPI 0x030800f0 - For Maintainers: Overview of Implementation ------------------------------------------- @@ -140,23 +107,12 @@ specified in ``pyproject.toml``). The builder then invokes ``python conanfile.py environment. The main reasons for this setting was to maintain the current default behaviour of ``conanfile.py``-based installation. -Editable installations (i.e. ``pip install -e .``) are not currently supported for two main reasons: - -1. ``pip install -e .`` is currently overridden to maintain the existing ``python conanfile.py`` behaviour. -2. Due to the underlying CMake build system, editable installs with ``pip`` require setting the - ``--no-build-isolation`` option, which means that the user must manually install the build requirements. - Since these build requirements are installed automatically by the standard ``conanfile.py`` installation, - it is the recommended method for editable installations. - -Tools such as `cibuildwheel `_ can be used to build wheels that are -automatically compatible with a broad range of operating system versions. These pre-compiled wheels can then -be shared publicly using tools like `twine `_ to upload them to the -`Python Package Index (PyPi) `_, allowing users to simply ``pip install Basilisk``. We -expect that these tools will be added into the Basilisk Continuous Integration pipeline in the future. - -Further discussions and implementation details can be found in -`Basilisk merge request #737 `_. +Editable installations (i.e. ``pip install -e .``) are are partially supported. Python code changes are reflected +automatically with this flag, but C++ components are not automatically rebuilt. +This limitation exists because editable mode still routes through ``python conanfile.py``, but skips C++ rebuilds +once the initial build exists. This avoids long native rebuilds and preserves the Conan/CMake configuration. +... .. rubric:: Footnotes From e3fab7219177e53399e6866ba39db0f7fb5cb0e6 Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Mon, 27 Oct 2025 08:28:17 -0600 Subject: [PATCH 05/15] Updated release notes --- docs/source/Support/bskReleaseNotes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/Support/bskReleaseNotes.rst b/docs/source/Support/bskReleaseNotes.rst index 1f4d52f181..aee246da8b 100644 --- a/docs/source/Support/bskReleaseNotes.rst +++ b/docs/source/Support/bskReleaseNotes.rst @@ -34,6 +34,7 @@ Version |release| and :ref:`thrusterDynamicEffector` attachable to :ref:`spinningBodyOneDOFStateEffector`, :ref:`spinningBodyTwoDOFStateEffector`, and :ref:`spinningBodyNDOFStateEffector`. - Added support for :ref:`linearTranslationOneDOFStateEffector` to attach dependent effectors. +- Improved documentation structure by separating build-from-source instructions from ``pip`` installation instructions. - Added custom reaction wheel: "NanoAvionics RW0" to ``src/utilities/simIncludeRW.py`` - Added TLE handling utilities in :ref:`tleHandling` to parse TLE files and convert to orbital elements - Removed deprecated use of astro constants from ``src/utilities/astroFunction.py``. From 2d459c594d1f98af3c85df4090b33c6268cd58c6 Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Fri, 19 Dec 2025 15:10:42 +0000 Subject: [PATCH 06/15] Create docs explaining the release process --- docs/source/Support/Developer.rst | 1 + .../source/Support/Developer/releaseGuide.rst | 195 ++++++++++++++++++ 2 files changed, 196 insertions(+) create mode 100644 docs/source/Support/Developer/releaseGuide.rst diff --git a/docs/source/Support/Developer.rst b/docs/source/Support/Developer.rst index b1720eee3b..1eaacad280 100644 --- a/docs/source/Support/Developer.rst +++ b/docs/source/Support/Developer.rst @@ -18,3 +18,4 @@ The following support files help with writing Basilisk modules. Developer/UnderstandingBasilisk Developer/migratingBskModuleToBsk2 Developer/MigratingToPython3 + Developer/releaseGuide diff --git a/docs/source/Support/Developer/releaseGuide.rst b/docs/source/Support/Developer/releaseGuide.rst new file mode 100644 index 0000000000..c08c2be99b --- /dev/null +++ b/docs/source/Support/Developer/releaseGuide.rst @@ -0,0 +1,195 @@ + +.. _releaseGuide: + +Release Guide + +================= + +These docs outline the process for releasing a new version of Basilisk. It is +intended for developers and maintainers of the Basilisk software. + +The high level steps to release a new version of Basilisk are as follows: + +1. **Update Version Number**: Modify the version number in `docs/source/bskVersion.txt` + to reflect the new release. +2. **Update Changelog**: Edit the release notes in `docs/source/Support/bskReleaseNotes.rst` file to include the changes. +3. **Create a Release Branch**: Create a new branch from the main development branch for the release. +4. **Create a Tag**: Once the release branch is ready, create a git tag for the new version. +5. **Create a release on GitHub**: Go to the GitHub repository and create a new release using the tag created in the previous step. + + +The following documentation provides detailed instructions for each of these steps. + +========================== +Updating the Version Number +=========================== + +The version number is stored in the `docs/source/bskVersion.txt` file. This file +gets read by the `pyproject.toml` during packaging to set the version of the +package. Previously, this file was updated automatically during the CI/CD +process; however, it must now be updated manually to prevent excessive version +bumps. + +Update this file to reflect the new version number following semantic versioning +guidelines (e.g., MAJOR.MINOR.PATCH). + +====================== +Updating the Changelog +====================== + +The changelog is located in the `docs/source/Support/bskReleaseNotes.rst` file. +Before releasing a new version, ensure that this file is updated to include +all relevant changes, bug fixes, and new features that are part of the release. + +========================= +Creating a Release Branch +========================= + +Active development occurs on the ``develop`` branch. Once all commits for a new +minor release have been merged into ``develop``, and the version number and +changelog have been updated, a new release branch should be created. + +The release branch is named after the minor version (e.g. ``3.9``) and is a +long-lived maintenance branch. It represents the released ``X.Y`` line and is +used for the initial release as well as any future patch releases (``X.Y.1``, +``X.Y.2``, etc.). + +To create a release branch: + +.. code-block:: bash + + git checkout develop + git pull origin develop + git checkout -b X.Y + git push -u origin X.Y + +Replace ``X.Y`` with the new minor version number (for example, ``3.9``). + +All patches and fixes for the ``X.Y`` release line must be made on this branch. +Any changes applied to the release branch should also be merged or cherry-picked +back into ``develop`` to ensure they are included in future releases. + +========================= +Creating and Pushing Tags +========================= + +Releases are published by pushing a git tag. Our GitHub Actions workflow +(``Publish Wheels``) is triggered on tag pushes matching: + +- ``v[0-9]*`` (real releases, published to PyPI) + +This means: **pushing a tag kicks off the wheel builds on all supported +platforms, builds an sdist, and then publishes the artifacts**. + +Tag format +---------- + +Release tags must follow the format ``vX.Y.Z`` (for example, ``v3.9.0``). + +Where to tag +------------ + +Tags for the ``X.Y`` release line must be created from the corresponding +maintenance branch (e.g. create ``v3.9.1`` from branch ``3.9``). + +Creating and pushing a release tag (publishes to PyPI) +------------------------------------------------------ + +.. code-block:: bash + + git checkout X.Y + git pull origin X.Y + git tag -a vX.Y.Z -m "Release vX.Y.Z" + git push origin vX.Y.Z + +Replace ``X.Y`` with the release branch name (e.g. ``3.9``) and ``X.Y.Z`` with +the full version (e.g. ``3.9.0``). + +Notes +----- + +- Tag pushes are immutable release triggers: once a tag is pushed, CI will build + and attempt to publish. If a mistake is made, prefer bumping the version and + tagging again rather than reusing the same version tag. +- After patching on ``X.Y``, merge or cherry-pick the fix back into ``develop`` + so the next release line also contains the change. + +============================= +Creating a Release on GitHub +============================= + +After pushing the release tag, create a new release on GitHub: + +1. Navigate to the GitHub repository for Basilisk. +2. Click on the "Releases" tab. +3. Click on "Draft a new release". +4. In the "Tag version" dropdown, select the tag you just pushed (e.g. ``vX.Y.Z``). +5. Fill in the release title and description, summarizing the changes included in this release. +6. Click "Publish release". + +This will make the release official and provide users with information about the new version. + +=========================== +Patch and Backport Workflow +=========================== + +Once a release branch (``X.Y``) exists, there may be multiple active branches at +the same time (e.g. ``develop``, ``3.9``, ``3.8``). To keep fixes consistent +across versions, we follow a strict patch and backport policy. + +General rule +------------ + +- **All fixes must be applied to every supported branch that needs them.** +- The fix should be authored on the *oldest applicable release branch* and then + cherry-picked forward. + +Where to make changes +--------------------- + +- **Bug fixes for an existing release**: + Start from the corresponding release branch (e.g. ``3.9``). + +- **New features or breaking changes**: + Go directly into ``develop`` (never into a release branch). + +Applying a patch release fix +---------------------------- + +Example: fixing a bug that affects the ``3.9`` release line. + +1. Create the fix on the ``3.9`` branch: + +.. code-block:: bash + + git checkout 3.9 + git pull origin 3.9 + git checkout -b fix/some-bug + # implement fix + git commit + +2. Merge the fix into ``3.9`` (via PR or direct merge). + +3. Cherry-pick the same commit(s) onto ``develop``: + +.. code-block:: bash + + git checkout develop + git pull origin develop + git cherry-pick + +If multiple release branches are active (e.g. ``3.8`` and ``3.9``), repeat the +cherry-pick for each newer branch as needed. + +Important notes +--------------- + +- **Never develop directly on multiple branches in parallel** for the same fix. + This leads to divergence and hard-to-resolve conflicts. +- **Do not merge ``develop`` back into ``X.Y``** after the release branch is + created. Release branches must remain stable and focused on fixes only. +- Cherry-picks should be small, focused, and preferably reference the original + commit hash in the message. + +After the fix has been merged into the release branch, create a new patch tag +(e.g. ``v3.9.1``) to publish the updated release. From 80a154f04b8a04e9505e80174e3466294b957fcb Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Fri, 19 Dec 2025 15:11:18 +0000 Subject: [PATCH 07/15] Update release notes --- docs/source/Support/bskReleaseNotes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/Support/bskReleaseNotes.rst b/docs/source/Support/bskReleaseNotes.rst index aee246da8b..8a96481e80 100644 --- a/docs/source/Support/bskReleaseNotes.rst +++ b/docs/source/Support/bskReleaseNotes.rst @@ -26,6 +26,7 @@ Basilisk Release Notes Version |release| ----------------- +- Added docs on releasing a new version of Basilisk. - Removed automated version bumping on merges to develop. Version bumps will be handled manually moving forward. - Added SWIG as a python package dependency in ``requirements_dev.txt`` and updated installation instructions. - Updated CI to no longer automatically publish git tags and publish wheels to PyPI. This process will be handled manually. From 2a8387e70c16db30fffe1e135e96fa4edfe46f24 Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Fri, 19 Dec 2025 16:45:40 +0000 Subject: [PATCH 08/15] Deploy beta docs and release docs --- .github/workflows/merge.yml | 1 + .github/workflows/publish-wheels.yml | 22 ++++++++++++++++++++++ 2 files changed, 23 insertions(+) diff --git a/.github/workflows/merge.yml b/.github/workflows/merge.yml index 6a3a00aef4..0aba0b7b22 100644 --- a/.github/workflows/merge.yml +++ b/.github/workflows/merge.yml @@ -35,4 +35,5 @@ jobs: with: github_token: ${{ secrets.GITHUB_TOKEN }} publish_dir: ./docs/build/html + destination_dir: beta force_orphan: true diff --git a/.github/workflows/publish-wheels.yml b/.github/workflows/publish-wheels.yml index d2bfd62f02..7d6106c081 100644 --- a/.github/workflows/publish-wheels.yml +++ b/.github/workflows/publish-wheels.yml @@ -118,3 +118,25 @@ jobs: uses: pypa/gh-action-pypi-publish@release/v1 with: packages-dir: dist + docs: + name: macOS Docs Deployment + needs: publish + runs-on: macos-latest + steps: + - uses: actions/checkout@v5 + with: + ref: ${{ github.ref }} + fetch-depth: 0 + - name: Build Basilisk + uses: ./.github/actions/build + with: + python-version: 3.13 + conan-args: --opNav True --allOptPkg --mujoco True --mujocoReplay True + - name: Build docs + uses: ./.github/actions/docs + - name: Deploy + if: ${{ success() }} # deploy only if prior steps ok + uses: peaceiris/actions-gh-pages@v3 + with: + github_token: ${{ secrets.GITHUB_TOKEN }} + publish_dir: ./docs/build/html From 46fb3c91edce8f4430d4e2d9631426d988233692 Mon Sep 17 00:00:00 2001 From: Reece Humphreys Date: Fri, 19 Dec 2025 16:46:04 +0000 Subject: [PATCH 09/15] Updated release notes --- docs/source/Support/bskReleaseNotes.rst | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/source/Support/bskReleaseNotes.rst b/docs/source/Support/bskReleaseNotes.rst index 8a96481e80..500cf4f920 100644 --- a/docs/source/Support/bskReleaseNotes.rst +++ b/docs/source/Support/bskReleaseNotes.rst @@ -26,6 +26,7 @@ Basilisk Release Notes Version |release| ----------------- +- Deploy both beta docs and release docs. - Added docs on releasing a new version of Basilisk. - Removed automated version bumping on merges to develop. Version bumps will be handled manually moving forward. - Added SWIG as a python package dependency in ``requirements_dev.txt`` and updated installation instructions. From 0e2c69c7a643f30eb42f7e296215a11f6797c5cb Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Fri, 19 Dec 2025 15:19:28 -0700 Subject: [PATCH 10/15] update info on BSK documentation links --- docs/source/index.rst | 5 ++--- 1 file changed, 2 insertions(+), 3 deletions(-) diff --git a/docs/source/index.rst b/docs/source/index.rst index 9b31ffb97a..e91c698caa 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -10,9 +10,8 @@ Welcome to Basilisk: an Astrodynamics Simulation Framework .. tip:: - This documentation is for the latest release on ``develop``. - If you are looking for documenation for prior tagged releases, they can be found at - `here `_. + The documentation for the tagged release is found at https://avslab.github.io/basilisk, + while the documentation for the latest beta release is found at https://avslab.github.io/basilisk/beta. Architecture ------------ From d76406998a757a5b271e8044151ba5024d8329f3 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Sat, 20 Dec 2025 14:00:20 -0700 Subject: [PATCH 11/15] add attention panel on cover page Highlight critical new features starting with v2.9.0 --- docs/source/index.rst | 12 ++++++++++++ 1 file changed, 12 insertions(+) diff --git a/docs/source/index.rst b/docs/source/index.rst index e91c698caa..b00cf5e0cc 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -13,6 +13,18 @@ Welcome to Basilisk: an Astrodynamics Simulation Framework The documentation for the tagged release is found at https://avslab.github.io/basilisk, while the documentation for the latest beta release is found at https://avslab.github.io/basilisk/beta. +.. attention:: + + Starting with Basilisk v2.9.0 we now: + + - create ``pip`` wheels on each tagged release. These are uploaded + automatically to `PyPI `_. See :ref:`bskInstall` for more info. + - tag major and patch releases on ``master``. The ``develop`` branch is used for the beta + cycle for the next major release. + - dynamically load Basilisk simulation data on demand. This keeps the wheel size acceptable + for `PyPi`_. See :ref:`bskInstall` for info on using ``bskLargeData`` to force all data to be + downloaded at once. + Architecture ------------ From 7257671e68f989ae22a8e2e511fc0d518d4c2bb8 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Fri, 19 Dec 2025 18:12:29 -0700 Subject: [PATCH 12/15] [squash] change sample number to 2.9.0 BSK v2.0.0 never had wheels built for it. --- docs/source/Install.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/Install.rst b/docs/source/Install.rst index 4b56d45bba..b10b7ecca9 100644 --- a/docs/source/Install.rst +++ b/docs/source/Install.rst @@ -38,7 +38,7 @@ To install a specific version, run: pip install bsk== -Replace ```` with the desired release number, e.g. ``2.0.0``. +Replace ```` with the desired release number, e.g. ``2.9.0``. **Prebuilt wheel availability:** From 9d97d90f75dc6a02ac0a80fda114dc80feae2028 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Fri, 19 Dec 2025 18:13:27 -0700 Subject: [PATCH 13/15] [squash] minor edits to pip install instructions - the created wheels are now called `bsk-...` not `basilisk-...` - fixed a path issue --- docs/source/Build/pipInstall.rst | 10 ++++------ 1 file changed, 4 insertions(+), 6 deletions(-) diff --git a/docs/source/Build/pipInstall.rst b/docs/source/Build/pipInstall.rst index 0119246a56..60ece601aa 100644 --- a/docs/source/Build/pipInstall.rst +++ b/docs/source/Build/pipInstall.rst @@ -44,17 +44,15 @@ Build options (as passed to ``conanfile.py`` and described in :ref:`configureBui Building Basilisk ``wheel`` File -------------------------------- -Using ``pip``, the command below will generate a ``Basilisk-*.whl`` file in the current directory:: +Using ``pip``, the command below will generate a ``bsk-*.whl`` file in the current directory:: pip wheel --no-deps -v . The resulting wheel file can then be installed using ``pip``:: - pip install Basilisk-*.whl + pip install bsk-*.whl -The main benefit of this approach will come in the future, when a set of pre-compiled wheels will be made available, -allowing most users to easily ``pip install Basilisk`` without compilation, in the same way that packages like -``numpy``, ``scipy``, and ``pandas`` are available. +This allows the user to create a custom Basilisk wheel to distribute within their organization. To keep the wheel size smaller, the large BSK data files are not installed by default. If the user wants to use script that assumes they are included into the Basilisk python package, then go to the @@ -74,7 +72,7 @@ package installation. If the computer does not have local internet access and the ``pip install`` is done via a local wheel, then these missing Spice ``*.bsp`` data files can be manually added to:: - .../.venv/lib/python3.11/site-packages/Basilisk/supportData/EphemerisData + .venv/lib/python3.11/site-packages/Basilisk/supportData/EphemerisData If installing Basilisk via a wheel the user does not have direct access to the full Basilisk source folder which contains the ``examples`` folder. The Terminal command ``bskExamples`` From eb0bbb85adc0a8fcfee3c2f62badb8abcf0e5c84 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Fri, 19 Dec 2025 18:14:02 -0700 Subject: [PATCH 14/15] [squash] updated comment in release notes now we have a hyperlink to this new documentation page --- docs/source/Support/bskReleaseNotes.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/source/Support/bskReleaseNotes.rst b/docs/source/Support/bskReleaseNotes.rst index 500cf4f920..d5188f747a 100644 --- a/docs/source/Support/bskReleaseNotes.rst +++ b/docs/source/Support/bskReleaseNotes.rst @@ -27,7 +27,7 @@ Basilisk Release Notes Version |release| ----------------- - Deploy both beta docs and release docs. -- Added docs on releasing a new version of Basilisk. +- Added :ref:`releaseGuide` on releasing a new version of Basilisk. - Removed automated version bumping on merges to develop. Version bumps will be handled manually moving forward. - Added SWIG as a python package dependency in ``requirements_dev.txt`` and updated installation instructions. - Updated CI to no longer automatically publish git tags and publish wheels to PyPI. This process will be handled manually. From 8c1a0f330885716273f0d69a682c2f2ee06224e9 Mon Sep 17 00:00:00 2001 From: Hanspeter Schaub Date: Fri, 19 Dec 2025 18:16:37 -0700 Subject: [PATCH 15/15] [squash] rewrote the release guide RST file I took my own release notes that I have been using and added steps I find helpful. I don't plan to maintain multiple prior releases v2.x.y for now. I'm just going to update the latest release on master and the beta on develop. Down the road I might choose to update earlier v2.X releases, but not to begin with. Once we do our first release I'm sure I might want to edit this again :-) Thanks for creating this file. I always had my own notes on my own computer. Now they are visible from the BSK documentation. Nice change. --- .../source/Support/Developer/releaseGuide.rst | 189 ++++++------------ 1 file changed, 66 insertions(+), 123 deletions(-) diff --git a/docs/source/Support/Developer/releaseGuide.rst b/docs/source/Support/Developer/releaseGuide.rst index c08c2be99b..5930ee2f0e 100644 --- a/docs/source/Support/Developer/releaseGuide.rst +++ b/docs/source/Support/Developer/releaseGuide.rst @@ -2,30 +2,39 @@ .. _releaseGuide: Release Guide - -================= +============= These docs outline the process for releasing a new version of Basilisk. It is intended for developers and maintainers of the Basilisk software. The high level steps to release a new version of Basilisk are as follows: -1. **Update Version Number**: Modify the version number in `docs/source/bskVersion.txt` - to reflect the new release. -2. **Update Changelog**: Edit the release notes in `docs/source/Support/bskReleaseNotes.rst` file to include the changes. -3. **Create a Release Branch**: Create a new branch from the main development branch for the release. -4. **Create a Tag**: Once the release branch is ready, create a git tag for the new version. -5. **Create a release on GitHub**: Go to the GitHub repository and create a new release using the tag created in the previous step. +#. Create a new branch ``v2_X_Y`` on ``develop`` for the release. +#. Modify the version number in ``docs/source/bskVersion.txt`` + to reflect the new release. +#. Add release date to ``docs/source/Support/bskReleaseNotes.rst`` + and ``docs/source/Support/bskKnownIssues.rst`` files. +#. Ensure documentation builds without warnings or errors. +#. Push branch to origin and do a PR. +#. Merge ``develop`` into ``master`` +#. Create a Release on GitHub +To prepare ``develop`` for the next beta cycle: -The following documentation provides detailed instructions for each of these steps. +#. Create ``beta_X_Y`` branch +#. Modify the version number in ``docs/source/bskVersion.txt`` + to reflect the new beta cycle such as ``v2_X_Y_beta``. +#. Update ``docs/source/Support/bskReleaseNotes.rst`` + and ``docs/source/Support/bskKnownIssues.rst`` files to next beta cycle +#. Make PR and push to ``develop`` -========================== -Updating the Version Number -=========================== -The version number is stored in the `docs/source/bskVersion.txt` file. This file -gets read by the `pyproject.toml` during packaging to set the version of the +The following documentation provides detailed instructions for some of these steps. + +Updating the Version Number +--------------------------- +The version number is stored in the ``docs/source/bskVersion.txt`` file. This file +gets read by the ``pyproject.toml`` during packaging to set the version of the package. Previously, this file was updated automatically during the CI/CD process; however, it must now be updated manually to prevent excessive version bumps. @@ -33,47 +42,31 @@ bumps. Update this file to reflect the new version number following semantic versioning guidelines (e.g., MAJOR.MINOR.PATCH). -====================== Updating the Changelog -====================== - -The changelog is located in the `docs/source/Support/bskReleaseNotes.rst` file. +---------------------- +The changelog is located in the ``docs/source/Support/bskReleaseNotes.rst`` file. Before releasing a new version, ensure that this file is updated to include all relevant changes, bug fixes, and new features that are part of the release. +Add a release date after the version number. -========================= Creating a Release Branch -========================= - +------------------------- Active development occurs on the ``develop`` branch. Once all commits for a new minor release have been merged into ``develop``, and the version number and changelog have been updated, a new release branch should be created. -The release branch is named after the minor version (e.g. ``3.9``) and is a +The release branch is named after the minor version (e.g. ``2.9``) and is a long-lived maintenance branch. It represents the released ``X.Y`` line and is used for the initial release as well as any future patch releases (``X.Y.1``, ``X.Y.2``, etc.). -To create a release branch: - -.. code-block:: bash - - git checkout develop - git pull origin develop - git checkout -b X.Y - git push -u origin X.Y - -Replace ``X.Y`` with the new minor version number (for example, ``3.9``). - All patches and fixes for the ``X.Y`` release line must be made on this branch. Any changes applied to the release branch should also be merged or cherry-picked back into ``develop`` to ensure they are included in future releases. -========================= Creating and Pushing Tags -========================= - -Releases are published by pushing a git tag. Our GitHub Actions workflow +------------------------- +Releases are published by pushing a git tag to the ``master`` branch. Our GitHub Actions workflow (``Publish Wheels``) is triggered on tag pushes matching: - ``v[0-9]*`` (real releases, published to PyPI) @@ -82,114 +75,64 @@ This means: **pushing a tag kicks off the wheel builds on all supported platforms, builds an sdist, and then publishes the artifacts**. Tag format ----------- - -Release tags must follow the format ``vX.Y.Z`` (for example, ``v3.9.0``). +^^^^^^^^^^ +Release tags must follow the format ``vX.Y.Z`` (for example, ``v2.9.0``). Where to tag ------------- - -Tags for the ``X.Y`` release line must be created from the corresponding -maintenance branch (e.g. create ``v3.9.1`` from branch ``3.9``). - -Creating and pushing a release tag (publishes to PyPI) ------------------------------------------------------- - -.. code-block:: bash - - git checkout X.Y - git pull origin X.Y - git tag -a vX.Y.Z -m "Release vX.Y.Z" - git push origin vX.Y.Z - -Replace ``X.Y`` with the release branch name (e.g. ``3.9``) and ``X.Y.Z`` with -the full version (e.g. ``3.9.0``). +^^^^^^^^^^^^ +Tags for the ``X.Y`` patch release line must be created from the corresponding +maintenance branch (e.g. create ``v2.9.1`` from branch ``2.9``). Notes ------ - +^^^^^ - Tag pushes are immutable release triggers: once a tag is pushed, CI will build and attempt to publish. If a mistake is made, prefer bumping the version and tagging again rather than reusing the same version tag. - After patching on ``X.Y``, merge or cherry-pick the fix back into ``develop`` so the next release line also contains the change. -============================= Creating a Release on GitHub -============================= - +---------------------------- After pushing the release tag, create a new release on GitHub: -1. Navigate to the GitHub repository for Basilisk. -2. Click on the "Releases" tab. -3. Click on "Draft a new release". -4. In the "Tag version" dropdown, select the tag you just pushed (e.g. ``vX.Y.Z``). -5. Fill in the release title and description, summarizing the changes included in this release. -6. Click "Publish release". +#. Go to “Code” tab, on right column select Releases +#. Select “Draft new Release” +#. Select correct commit on ``master`` +#. Add title “Basilisk v2.x.x” +#. Add release notes +#. Remove all ``:ref:`` statements from release notes +#. Add release tag ``v2.X.Y``. +#. Bottom of page, press “Publish Release” button This will make the release official and provide users with information about the new version. -=========================== Patch and Backport Workflow -=========================== - -Once a release branch (``X.Y``) exists, there may be multiple active branches at -the same time (e.g. ``develop``, ``3.9``, ``3.8``). To keep fixes consistent -across versions, we follow a strict patch and backport policy. - -General rule ------------- - -- **All fixes must be applied to every supported branch that needs them.** -- The fix should be authored on the *oldest applicable release branch* and then - cherry-picked forward. +--------------------------- +Once a release branch (``X.Y``) exists we only maintain this latest ``X.Y`` release on ``master`` +and the current beta on ``develop``. Where to make changes ---------------------- - -- **Bug fixes for an existing release**: - Start from the corresponding release branch (e.g. ``3.9``). - +^^^^^^^^^^^^^^^^^^^^^ - **New features or breaking changes**: - Go directly into ``develop`` (never into a release branch). - -Applying a patch release fix ----------------------------- - -Example: fixing a bug that affects the ``3.9`` release line. - -1. Create the fix on the ``3.9`` branch: - -.. code-block:: bash - - git checkout 3.9 - git pull origin 3.9 - git checkout -b fix/some-bug - # implement fix - git commit + Go directly into ``develop`` for the next beta cycle (never into a release branch). -2. Merge the fix into ``3.9`` (via PR or direct merge). - -3. Cherry-pick the same commit(s) onto ``develop``: - -.. code-block:: bash - - git checkout develop - git pull origin develop - git cherry-pick +- **Bug fixes for an existing release**: -If multiple release branches are active (e.g. ``3.8`` and ``3.9``), repeat the -cherry-pick for each newer branch as needed. + #. Create branch on develop to test the fix. + #. Create PR for this fix branch, don't update beta release notes + #. On master, create a patch branch and cherry pick over the fix commit(s) + #. On the patch branch, update the release notes for ``v2.X.Y`` with a release date + #. Merge this branch into ``master`` + #. Create a Release on GitHub + #. Charry pick the commit that updated the ``v2.X.Y`` release notes back into + the beta cycle on ``develop``. -Important notes ---------------- -- **Never develop directly on multiple branches in parallel** for the same fix. - This leads to divergence and hard-to-resolve conflicts. -- **Do not merge ``develop`` back into ``X.Y``** after the release branch is - created. Release branches must remain stable and focused on fixes only. -- Cherry-picks should be small, focused, and preferably reference the original - commit hash in the message. +.. important:: -After the fix has been merged into the release branch, create a new patch tag -(e.g. ``v3.9.1``) to publish the updated release. + - Never develop directly on multiple branches in parallel for the same fix. + This leads to divergence and hard-to-resolve conflicts. + - Do not merge ``develop`` back into ``X.Y`` after the release branch is + created. Release branches must remain stable and focused on fixes only. + - Cherry-picks should be small, focused, and preferably reference the original + commit hash in the message.