Merge pull request #11 from NVIDIA-NeMo/docs/releasing-github

docs: rewrite RELEASING.md for GitHub + current package set

Author: rdasilveiracabral

RELEASING.md

@@ -1,111 +1,85 @@
-# Releasing nemo-oo-agents
+# Releasing
 
-Three workspace packages — `nemo-oo-agents`, `nooa-cli`, and
-`nemo-oo-agents-benchmarks` — release together from the same git commit.
-Version is derived from `git describe` at build time by
-[`uv-dynamic-versioning`](https://github.com/ninoseki/uv-dynamic-versioning).
+Four workspace packages release together from the same git commit:
+
+- **`nooa`** — the core framework
+- **`nooa-cli`** — the `nooa` command and REPL
+- **`nooa-memory`** — the long-term memory subsystem
+- **`nooa-bench`** — the benchmark agent and Harbor runner
 
-There is no `version = "..."` in any pyproject.toml and no manual bump step
-between releases. **Tagging the commit is the entire release ceremony.**
+The version is derived from the git **tag** at build time by
+[`uv-dynamic-versioning`](https://github.com/ninoseki/uv-dynamic-versioning).
+There is no `version = "..."` in any `pyproject.toml` and no manual bump step.
+**Tagging the commit is the release ceremony.**
 
-## Continuous publishes (every main commit)
+## Versioning
 
-Every push to `main` triggers `build-package-*` and `publish-package-*` jobs.
-The published version is derived from the last `vX.Y.Z` tag reachable from
-the commit, plus the distance to that tag:
+The version comes from the last `vX.Y.Z` tag reachable from the commit, plus
+the distance to that tag:
 
-| Repo state | Wheel version |
+| Repo state | Version |
 |---|---|
-| Exactly on tag `v0.3.0` | `0.3.0` |
-| 5 commits past `v0.3.0` | `0.3.1.dev5` |
-| No `vX.Y.Z` tag reachable yet | `0.0.1.dev<commit-count>` (until first tag — see "Bootstrapping") |
+| Exactly on tag `v0.0.6` | `0.0.6` |
+| 5 commits past `v0.0.6` | `0.0.7.dev5` |
+| No `vX.Y.Z` tag reachable yet | `0.0.1.dev<distance>` |
 
-> Note: the `fallback-version = "0.0.6"` in pyproject.toml is the version
-> used only when git itself is unavailable (e.g. building from an unpacked
-> sdist with no `.git` dir). In CI git is always present, so the version
-> is always derived from `git describe` — the fallback never fires.
+> `fallback-version = "0.0.6"` in `pyproject.toml` is used **only** when git
+> is unavailable (e.g. building from an unpacked sdist with no `.git/`).
+> Whenever git is present, the version is derived from `git describe`.
 
-Dev versions sort *above* the latest stable release and *below* the next
-stable, so `--pre` consumers always get the freshest dev:
+This is a `0.x` **research preview** — the public API is not yet stable and may
+change between releases (per [SemVer](https://semver.org/), `0.y.z` signals
+initial development).
 
-```bash
-# Latest dev wheel from main
-uv add nemo-oo-agents --pre
+## Cutting a release
 
-# Pin to a specific dev wheel
-uv add nemo-oo-agents==0.3.1.dev5
+```bash
+git checkout main && git pull
+git tag -a v0.0.6 -m "NOOA 0.0.6 — research preview"
+git push origin v0.0.6
 ```
 
-`uv add nemo-oo-agents` (no `--pre`) keeps picking the last stable release.
-
-## Bootstrapping (one-time, after this MR merges)
-
-Until a `vX.Y.Z` tag exists in the repo, dev publishes ship as
-`0.0.1.dev<commit-count>` — derived from "0 tags reachable" + the `bump = true`
-config. To switch dev publishes to a meaningful base, cut the first tag:
+Build the four packages from the tagged commit:
 
 ```bash
-git checkout main
-git pull
-git tag -a v0.2.0 -m "Initial release with dynamic versioning"
-git push origin v0.2.0
+rm -rf dist
+for p in nooa nooa-cli nooa-memory nooa-bench; do
+  uv build --package "$p" --out-dir dist
+done
 ```
 
-Subsequent main pushes will then publish as `0.2.1.dev<distance>`. After
-that, the rest of this doc is the entire release process.
-
-## Cutting a stable release
+**Smoke-test the wheels in a clean environment** before publishing:
 
 ```bash
-git checkout main
-git pull
-git tag -a v0.3.0 -m "Release 0.3.0"
-git push origin v0.3.0
+python3.12 -m venv /tmp/nooa-smoke && . /tmp/nooa-smoke/bin/activate
+pip install dist/nooa-*.whl dist/nooa_cli-*.whl dist/nooa_memory-*.whl dist/nooa_bench-*.whl
+python -c "import nooa, nooa_cli, nooa_memory, nooa_bench; print(nooa.__version__)"
+nooa --version
+deactivate
 ```
 
-That's it. The tag pipeline builds and publishes `0.3.0` of all three
-packages to the GitLab Package Registry. No pyproject changes, no follow-up
-MRs, no version bumps anywhere.
-
 ### Pre-release tags
 
-CI accepts annotated tags matching `^v\d+\.\d+\.\d+([.-][a-zA-Z0-9]+)?$`,
-which covers pre-release suffixes:
-
-```bash
-git tag -a v0.3.0-rc1 -m "Release candidate"
-git push origin v0.3.0-rc1
-```
+Annotated tags like `v0.0.6-rc1` build as `0.0.6rc1` (PEP 440 normalized).
 
-The wheel ships as `0.3.0-rc1` (PEP 440 normalizes to `0.3.0rc1`).
+## Distribution
 
-## Cross-package dependencies
+The packages are currently distributed as **source** — install directly from
+GitHub at a tag:
 
-`nooa-cli` and `nemo-oo-agents-benchmarks` declare their
-dependency on core as a static lower-bound floor in their pyproject.toml:
-
-```toml
-"nemo-oo-agents>=0.2.0",
+```bash
+uv add "nooa @ git+https://github.com/NVIDIA-NeMo/labs-OO-Agents.git@v0.0.6"
 ```
 
-The floor reflects the actual minimum-compatible core version. **Bump it in
-a normal MR when the package starts to require a newer core API** — same as
-you would for any third-party dep. CI does not rewrite this declaration.
+Optionally attach the built wheels to a **GitHub Release** for the tag.
 
-## Republishing a main commit
+> **PyPI publishing is not yet enabled.** When it is, a GitHub Actions workflow
+> (PyPI Trusted Publishing) will build and upload all four packages on each
+> `vX.Y.Z` tag. The names `nooa`, `nooa-cli`, `nooa-memory`, and `nooa-bench`
+> are available on PyPI and can be reserved ahead of the first publish.
 
-`uv publish` is not idempotent against the GitLab Package Registry — a
-second attempt with the same version returns HTTP 400. CI does not retry
-publish jobs.
-
-If a transient failure leaves a dev publish broken, **push an empty commit**
-to advance the dev version:
-
-```bash
-git commit --allow-empty -m "ci: re-trigger publish"
-git push
-```
+## Cross-package dependencies
 
-Do NOT use the GitLab "Retry pipeline" button on the build stage — it
-rebuilds at the same git HEAD and therefore the same derived version, which
-then 400s on publish.
+`nooa-cli`, `nooa-memory`, and `nooa-bench` depend on the core `nooa` package.
+They are always released together at the same derived version, so their
+dependency on `nooa` carries **no version floor** — CI never rewrites it.