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 Python and 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

Run the following command from vehicle-python:
```
pipx run tox
```
Vehicle documentation tests

Run the following command from docs:
```
pipx run tox
```
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:
```
pipx run tox
```
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.14.0-cp310-cp310-macosx_13_0_arm64.whl
vehicle_lang-0.14.0-cp37-cp37m-macosx_13_0_arm64.whl
vehicle_lang-0.14.0-cp39-cp39-macosx_13_0_arm64.whl
vehicle_lang-0.14.0-cp311-cp311-macosx_13_0_arm64.whl
vehicle_lang-0.14.0-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.14.0