From 02892bec178d932c8fbeb9c11c1386c260ef4f9f Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?Alexis=20M=C3=A9taireau?= <alexis@notmyidea.org>
Date: Fri, 5 Apr 2024 15:15:59 +0200
Subject: [PATCH] build: document the release process

---
 docs/developer/release.md | 82 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 82 insertions(+)
 create mode 100644 docs/developer/release.md

diff --git a/docs/developer/release.md b/docs/developer/release.md
new file mode 100644
index 0000000..da39138
--- /dev/null
+++ b/docs/developer/release.md
@@ -0,0 +1,82 @@
+# Releasing guide
+
+Once in a while, we release this package. Here is how.
+
+## Pre-requesites
+
+You need to be in a working environment, with the dev dependencies installed. You can check it's the case by typing:
+
+```bash
+pip install -e ".[dev]"
+```
+
+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
+
+# Ensure the tests run correctly
+make test
+
+# Bump the version, according to semantic versionning
+hatch version minor # or `hatch version major``
+
+# Create a tag on the git repository and push it
+git tag "$(hatch version)" && git push
+
+# Build the project
+hatch build --clean
+
+# Upload the project to PyPI
+hatch publish
+```
+
+Aditionnaly, ensure it works well in a new environment.
+
+## Bumping the version number
+
+We follow semantic versionning conventions, and the version is specified in the `argos.__init__.py` file.
+`hatch` provide commands to help with this:
+
+```bash
+hatch version minor
+hatch version major
+```
+
+## Publishing
+
+`hatch` will ask you for some credentials. Don't provide them the full credentials to you account, but instead you can [create a (scoped) token](https://pypi.org/manage/account/token/).
+
+When asked for credentials, enter:
+
+- `__token__` as the login
+- the token as the value.
+
+## Verifying it worked
+
+Once published, you can test it works properly, by using pip, ideally in a new venv. Here's how:
+
+```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 `hatch 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
+hatch build -r test
+
+# Installing from test PyPI
+pip install --index-url https://test.pypi.org/simple/ argos-monitoring
+
+```
\ No newline at end of file