12  Core library

The development focuses on portability and ease of setup, so by default any dependency relying on a C/C++ compiler is forbidden. This means that the development environment can be set up on any platform without needing to install additional compilers or tools.

Majordome code is documented using Numpydoc style docstrings, and the documentation is generated by module majordome.documents using Quarto markdown. This design choice reflects the academic aim of the package, with reporting and notebook support as first-class citizens.

The environment for developing Majordome requires at least a reasonably modern version of Python and Rust; documentation depends on Quarto and uv is used for managing the environment. The exact versions may change over time, but as of the last update, the following (minimum) versions are recommended:

• Python 3.12+
• Rust toolchain
• Quarto CLI
• uv

Tip

Ubuntu users can bootstrap the environment with the following commands; make sure to check the latest versions of the tools and update the commands accordingly. Podman is required for building the manylinux wheel inside a container for compatibility and release in PyPI.

sudo apt-get install -y podman
sudo apt-get install -y python3-dev

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh -s -- -y
source "$HOME/.cargo/env"

curl -LsSf https://astral.sh/uv/install.sh | sh
source "$HOME/.local/bin/env"

quarto_repo="https://github.com/quarto-dev/quarto-cli"
quarto_deb="quarto-1.9.37-linux-amd64.deb"

wget $quarto_repo/releases/download/v1.9.37/$quarto_deb
sudo apt-get install -y ./$quarto_deb

12.1 Release process

In addition to what is described in the manual builds section, developers can also need to publish the docs, update the version, and publish the new version to GitHub and PyPI. This is fully automated by release.ps1 to ensure consistency in actions.

• Make sure the package builds in both Windows and Linux, and that the documentation builds (many tests are included in the documentation, so this is a good sanity check for the code as well). The following commands provide a good starting point for the verifications in Windows:

# Check the sanity of the package:
cargo check

# Run Rust tests:
cargo test

# Run Python tests:
uv sync --all-extras
pytest -v

# Manually generate a wheel and check it:
uv build --wheel
python -m zipfile -l dist/*.whl

• From WSL or a Linux machine, repeat the above but also try generating the Linux wheel inside the compliant manylinux container:

./release.sh

• Once verifications are done, run one of the following:

# - You fixed something small:
./release.ps1 patch

# - You added a new (non-breaking) feature:
./release.ps1 minor

# - You made a breaking change:
./release.ps1 major

# - Avoid this, unless you know exactly what you are doing:
./release.ps1 1.0.0

12.2 Manual release steps

This script is useful but can be fragile; it is better to have a fall-back plan in case something goes wrong.

• Select the new version to release:

$version = "major"
$version = "minor"
$version = "patch"

• Update the version in both Cargo.toml and pyproject.toml:

# First, test with --dry-run to check the changes that will be made:
uv version --bump $version --dry-run
cargo set-version --bump $version --dry-run

# After testing with the above, remove --dry-run:
uv version --bump $version
cargo set-version --bump $version

• You can manually check the changes in the version files; alternatively, the following snipet can be used to extract the version from Cargo.toml and use it for the commit message and GitHub release tag:

$inSection = $false
$version = $null

foreach ($line in Get-Content "Cargo.toml") {
    if ($line -match '^\[(.+)\]\s*$') {
        $inSection = $Matches[1] -eq "package"
        continue
    }

    if ($inSection -and $line -match '^version\s*=\s*"([^"]+)"') {
        $version = $Matches[1]
        break
    }
}

• Generate the command for WSL build and inspect it before running:

$winPath = (Get-Location).Path.Replace("\", "/")
$wslPath = (wsl wslpath $winPath).Trim()
$nixCmd  = "cd $wslPath && source ~/.bashrc && ./release.sh"

• Build the wheels in both Windows and Linux (inside the compliant manylinux container):

Remove-Item -Force -Recurse "dist/" -ErrorAction Ignore

uv build --wheel
wsl -d Ubuntu -- bash -c $nixCmd

• Inspect the wheels (especially if new data was included):

python -m zipfile -l dist/*.whl

• If everything is fine, commit the changes, push to the repository:

git add "Cargo.toml" "pyproject.toml" "Cargo.lock" "uv.lock"
git commit -m "Release version $version"
git tag "v$version"
git push origin main --tags

• Create and activate a virtual environment:

uv venv --python python3.12 .venv

# Activate on Windows:
. .venv/Scripts/activate

# Activate on Unix:
. .venv/bin/activate

• Install the package before generating the documentation:

uv pip install .[docs]

• Point Quarto to the virtual environment:

# Windows:
$env:QUARTO_PYTHON = ".venv/Scripts/python.exe"

# Unix:
export QUARTO_PYTHON=".venv/bin/python"

• Generate the documentation and publish it to GitHub Pages:

quarto render docs --to html
quarto publish gh-pages --no-prompt --no-browser docs

• Create the release on GitHub:

gh release create "v$version" dist/*.whl --generate-notes

• Publish the new version to PyPI (owners only) is done manually with uv:

uv publish