From 45641f8e2c39e80e373b6f3233afe84820205b8a Mon Sep 17 00:00:00 2001
From: Latte <latte@hiddenden.cafe>
Date: Sat, 27 Jun 2026 15:59:37 +0200
Subject: [PATCH] docs: document dev and stable package channels

Document the two publish channels (aegis-gitea-mcp from main,
aegis-gitea-mcp-dev from dev), install commands for each, that both share
the aegis_gitea_mcp module so only one installs per environment, and the
merge-driven stable release flow (bump version -> PR into dev -> promote
dev to main; re-pushing main at the same version is a --check-url no-op).
---
 docs/packaging.md | 71 +++++++++++++++++++++++++++++++++++------------
 1 file changed, 53 insertions(+), 18 deletions(-)

diff --git a/docs/packaging.md b/docs/packaging.md
index 14f04da..32323f2 100644
--- a/docs/packaging.md
+++ b/docs/packaging.md
@@ -1,12 +1,23 @@
 # Packaging & publishing
 
-AegisGitea-MCP is distributed as a single Python package, `aegis-gitea-mcp`,
-built with [`uv`](https://docs.astral.sh/uv/) and published to the self-hosted
-Gitea package registry.
+AegisGitea-MCP is built with [`uv`](https://docs.astral.sh/uv/) and published to
+the self-hosted Gitea package registry on every merge. There are two channels:
+
+| Channel | Package | Published on | Versioning |
+|---------|---------|--------------|------------|
+| **stable** | `aegis-gitea-mcp` | merge to `main` | `X.Y.Z` |
+| **dev** | `aegis-gitea-mcp-dev` | merge to `dev` | `X.Y.Z.devN` (N = CI run number, always unique) |
+
+Both channels build from the same source and install the **same import module**,
+`aegis_gitea_mcp`, with the same two console scripts. They differ only in the
+distribution name and the version. Install one or the other in a given
+environment, not both — they would collide on the module.
 
 ## Distribution layout
 
-One package, two console scripts, one optional extra:
+Each channel ships one distribution with two console scripts and one optional
+extra (the stable and dev packages are identical here — only the dist name and
+version differ):
 
 | Console script | Entry point | Requires |
 |----------------|-------------|----------|
@@ -39,30 +50,54 @@ GITEA_URL=https://git.hiddenden.cafe GITEA_TOKEN=<pat> \
 
 ## Install from the Gitea registry
 
+**Stable** (`aegis-gitea-mcp`, published from `main`):
+
 ```bash
 uv pip install \
-  --index-url https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple \
+  --index-url https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ \
   aegis-gitea-mcp
+
+# or run it one-off without installing into the environment:
+uvx --index https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ aegis-gitea-mcp
 ```
 
-(With `pip`, use `--index-url` the same way.)
+**Dev** (`aegis-gitea-mcp-dev`, published from `dev` — newest pre-release build):
 
-## Cutting a release
+```bash
+uv pip install \
+  --index-url https://git.hiddenden.cafe/api/packages/Hiddenden/pypi/simple/ \
+  aegis-gitea-mcp-dev
+```
 
-Releases are tag-driven. The publish workflow
-(`.gitea/workflows/publish.yml`) triggers on a `v*` tag, runs lint + tests
-first, builds with `uv`, and publishes to the Gitea PyPI registry.
+(With `pip`, use `--index-url` the same way.) Both packages expose the same
+`aegis-gitea-mcp` / `aegis-gitea-mcp-server` console scripts and the same
+`aegis_gitea_mcp` import module, so install one **or** the other per environment.
 
-1. Bump `version` in `pyproject.toml` (e.g. `0.2.0`).
-2. Open a PR into `dev`, merge `dev` into `main`.
-3. Tag the release commit and push the tag:
+## Publishing channels
 
-   ```bash
-   git tag v0.2.0
-   git push origin v0.2.0
-   ```
+Publishing is merge-driven, not tag-driven. The publish workflow
+(`.gitea/workflows/publish.yml`) triggers on a push to `dev` or `main`, runs
+lint + tests first, then builds with `uv` and publishes to the Gitea PyPI
+registry. The package name + version are patched into `pyproject.toml` **at build
+time only** (never committed):
 
-4. The workflow publishes the wheel + sdist and attaches them to the run.
+- **`dev` push** → `aegis-gitea-mcp-dev` at `X.Y.Z.dev<run_number>`. The CI run
+  number is monotonic, so every merge to `dev` yields a unique pre-release.
+- **`main` push** → `aegis-gitea-mcp` at the plain `X.Y.Z` from `pyproject.toml`.
+  Publishing uses `uv publish --check-url`, so a `main` push that did **not** bump
+  the version is a clean no-op (the existing files are skipped) rather than a 409.
+
+### Cutting a stable release
+
+1. Bump `version` in `pyproject.toml` (e.g. `0.2.0` → `0.3.0`) on a branch off
+   `dev`.
+2. Open a PR into `dev` and merge it (this publishes a fresh
+   `aegis-gitea-mcp-dev` build).
+3. Promote `dev` → `main`. The push to `main` publishes the new stable
+   `aegis-gitea-mcp X.Y.Z`.
+
+Re-pushing `main` at an unchanged version is harmless — `--check-url` skips the
+already-published files.
 
 ### Required CI secrets