---
description: Once in a while, we release this package. Here is how.
---
# Releasing guide

Once in a while, we release this package. Here is how.

## Pre-requisites

You need to have [uv](https://docs.astral.sh/uv/) installed. You can install it with:

```bash
curl -LsSf https://astral.sh/uv/install.sh -o uv-install.sh
# Check that it does not anything evil
less uv-install.sh
# If ok, execute it
sh uv-install.sh &&
  rm uv-install.sh
```

You'll need to get an account on [PyPI](https://pypi.org), where the packages will be uploaded.

## The steps

Here is the quick version. If you need more details, some parts are explained in more details in the next sections.

```bash
# Be sure you are on the good branch
git checkout main

# Sync dependencies and update the lock file
uv sync --all-extras --active

# Ensure the tests run correctly
make test

# Check static typing
make mypy
make ty

# Bump the version
# You can choose major, minor, patch, stable, alpha, beta, rc, post, dev
# see uv version --help
uv version --active --bump <version>

# Get the current version for `argos/__init__.py` and changelog
VERSION=$(uv version --short)

# Update the version in `argos/__init__.py`
sed -e "s/VERSION = \".*/VERSION = \"${VERSION}\"/" -i argos/__init__.py

# Update the changelog
sed -e "s/## .Unreleased./&\n\n## ${VERSION}\n\nDate: $(date +%F)/" \
    -i CHANGELOG.md

# Commit the change
git add pyproject.toml argos/__init__.py CHANGELOG.md uv.lock
git commit -m "🏷 — Bump version (${VERSION})"

# Create a tag on the git repository and push it
git tag "${VERSION}" -m "${VERSION}" &&
  git push --follow-tags

# Build the project
uv build --clear

# Upload the project to PyPI
uv publish
```

Additionally, ensure it works well in a new environment.

## Bumping the version number

We follow semantic versioning conventions. The version is specified in the `pyproject.toml` file under `[project]`.

## Publishing

`uv publish` will ask you for some credentials. Don't provide the full credentials to your account, but instead you can [create a (scoped) token](https://pypi.org/manage/account/token/).

When asked for credentials, enter:

- `__token__` as the username
- the token as the password.

Alternatively, you can set the `UV_PUBLISH_TOKEN` environment variable:

```bash
export UV_PUBLISH_TOKEN=your-token-here
uv publish
```

## Verifying it worked

Once published, you can test it works properly using `uv`, ideally in a new environment. Here's how:

```bash
# Using uv to test installation
uv run --with argos-monitoring argos version
```

Or if you prefer to test with a traditional virtual environment:

```bash
python -m venv /tmp/argos
source /tmp/argos/bin/activate
pip install argos-monitoring
argos version # should output the proper version
```

## Using the test server

When running `uv publish` the main PyPI instance will be used, which is not ideal for testing that it's doing what you want.

If you're still experimenting, you can use the [Test PyPI](https://test.pypi.org) server.

```bash
# Publishing on test PyPI
uv publish --publish-url https://test.pypi.org/legacy/

# Installing from test PyPI
uv pip install --index-url https://test.pypi.org/simple/ argos-monitoring
```