Publishing a release

Vehicle is released via PyPI, the Python Package Index.

Ensure that you have the source code and that you have installed both GHC and Cabal and a supported Python interpreter plus pipx.

To publish new releases to PyPI, you need a PyPI account that is authorised as a collaborator on the vehicle_lang project, and you need to create a PyPI API token for that account and add it to your .pypirc file.

Finally, you need access to a machine running macOS with an M1/M2 chipset.

The procedure to create a new release is:

Navigate to your local copy of the Vehicle repository.
Ensure that you are on the default branch dev.
Ensure that all changes are committed and pushed.
Ensure that the tests are passing on CI: https://github.com/vehicle-lang/vehicle/actions/workflows/ci.yml?query=branch%3Adev
Run all tests and fix any errors.

Vehicle compiler tests

Run the following command from the root of the repository:

cabal test all --test-option=--num-threads=1

Vehicle Python bindings tests

From vehicle-python, ensure the lockfile is current, then execute the pytest matrix:

uv sync --extra test --extra pygments --extra pytorch --extra tensorflow
for version in 3.10 3.11 3.12 3.13; do
  UV_PYTHON_PREFERENCE=managed \
    uv run --python "${version}" --extra test --extra pygments python -m pytest
done

Add any pytest arguments (for example -k test_main) to the python -m pytest invocation. When TensorFlow wheels aren’t available on your platform, drop --extra tensorflow from the uv sync line. See the compiler testing guidance above for more background.

Vehicle documentation tests

Run the following commands from docs to build the Sphinx documentation via the local pyproject:

cd docs
uv sync
uv run sphinx-build -nW --keep-going -b html . _build/html

uv sync creates (or updates) .venv inside docs/ and keeps it in lockstep with docs/pyproject.toml and docs/uv.lock.

If any errors occur, fix them, and restart from step 1.

Choose the appropriate version number to increase.
- If you’re increasing the major version, run this command:
```
pipx run bumpver update --major --dry
```
- If you’re increasing the minor version, run this command:
```
pipx run bumpver update --minor --dry
```
- If you’re increasing the patch version, run this command:
```
pipx run bumpver update --patch --dry
```
The output will contain a diff of the changes to be made.

If the diff looks reasonable, rerun the command without the --dry flag.

This will update the version, create a Git tag, and push it to GitHub.
Ensure that the CI successfully builds and publishes Vehicle to PyPI: https://github.com/vehicle-lang/vehicle/actions/workflows/ci.yml?query=branch%3Adev

Add identifiers for the new version to CITATION.cff at the top of the list under the identifiers key.

You can use the following as a template:

- type: url
 value: "https://github.com/vehicle-lang/vehicle/releases/tag/v0.13.0"
 description: "The GitHub release URL of tag v0.13.0."
- type: url
   value: "https://gpypi.org/project/vehicle-lang/0.13.0/"
   description: "The PyPI release URL of version 0.13.0."

On a macOS machine with an M1/M2 chipset

There are no GitHub Actions runners with an M1/M2 chipset, so the binary distributions for this platform must be built and published manually from an appropriate machine.

Run the following command from vehicle-python to build and delocate the wheels using the helper script:

uv run --extra wheel scripts/build-wheel.sh

This creates the directory dist which contains “wheels”, which are the binary distribution format for Python packages. If you’re on macOS with an M1/M2 chipset, these look like:

vehicle_lang-0.25.1-cp310-cp310-macosx_13_0_arm64.whl
vehicle_lang-0.25.1-cp37-cp37m-macosx_13_0_arm64.whl
vehicle_lang-0.25.1-cp39-cp39-macosx_13_0_arm64.whl
vehicle_lang-0.25.1-cp311-cp311-macosx_13_0_arm64.whl
vehicle_lang-0.25.1-cp38-cp38-macosx_13_0_arm64.whl

Run the following command to check each wheel’s metadata:

pipx run twine check --strict dist/*.whl

Warning: The following is a destructive action! Published versions cannot be changed!

Run the following command to upload each wheel to PyPI:

pipx run twine upload dist/*.whl

Edit the release on GitHub and add the wheel files in dist/.

The release will be at a URL like:

https://github.com/vehicle-lang/vehicle/releases/tag/v0.25.1