From 5b947b1452890eebd23e38aa966813d4cb76881b Mon Sep 17 00:00:00 2001 From: Otavio Salvador Date: Sun, 14 Jun 2026 22:45:02 -0300 Subject: [PATCH] docs: split CLAUDE.md into linked guides Apply progressive disclosure to the agent instructions: keep only the project description and file layout in CLAUDE.md, and move the task-specific sections into docs/ so they load only when relevant. - docs/releasing.md: the vX.Y.Z / vX tag model and release steps (read when tagging or moving a tag). - docs/marketplace.md: the action.yml Marketplace constraints (read when editing it). Content is moved verbatim; CLAUDE.md links to both. --- CLAUDE.md | 41 +++++------------------------------------ docs/marketplace.md | 9 +++++++++ docs/releasing.md | 31 +++++++++++++++++++++++++++++++ 3 files changed, 45 insertions(+), 36 deletions(-) create mode 100644 docs/marketplace.md create mode 100644 docs/releasing.md diff --git a/CLAUDE.md b/CLAUDE.md index 95500ce..eee5e35 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -11,40 +11,9 @@ Marketplace as **OSSystems Nix Actions** `OSSystems/nix-actions/update-flake@v1`. Not separately listed (one Marketplace listing per repo). -## Versioning +## Guides -Two kinds of tags, both on the same release commit: - -- `vX.Y.Z` (e.g. `v1.0.0`) — **immutable**. Matches a published Marketplace - release; never move it once published. -- `vX` (e.g. `v1`) — **movable major tag**. Most callers pin `@v1`, so it must - be fast-forwarded to each new release on the same major line. `v1` is a *tag*, - not a branch. - -## Cutting a new release - -1. Land all changes on `main`. -2. Tag the immutable version and push it: - ``` - git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z - ``` -3. Move the major tag to the same commit: - ``` - git tag -f vX HEAD && git push -f origin vX - ``` -4. Create the GitHub release from the `vX.Y.Z` tag - (`gh release create vX.Y.Z --title vX.Y.Z --notes ...`). On the **first** - release of a major line, also check "Publish this Action to the GitHub - Marketplace" in the release UI (the Marketplace checkbox is UI-only) and - accept the Developer Agreement. - -For a docs/non-release change that should reach `@v1` callers without a new -version, just move the major tag: `git tag -f v1 HEAD && git push -f origin v1`. - -## Marketplace constraints (when editing `action.yml`) - -- `name` must be globally unique across all Marketplace actions, users, and - orgs — hence the `OSSystems` prefix. -- `description` must be under 125 characters. -- `branding.icon` / `branding.color` are required to publish; keep them set. -- The publishing org must have 2FA enabled. +- [Releasing](docs/releasing.md) — the `vX.Y.Z` (immutable) and `vX` (movable) + tag model and the steps to cut a release. Read before tagging or moving a tag. +- [Marketplace constraints](docs/marketplace.md) — rules the published + `action.yml` must satisfy. Read before editing it. diff --git a/docs/marketplace.md b/docs/marketplace.md new file mode 100644 index 0000000..03d8ea3 --- /dev/null +++ b/docs/marketplace.md @@ -0,0 +1,9 @@ +# Marketplace constraints + +Honor these when editing `action.yml`: + +- `name` must be globally unique across all Marketplace actions, users, and + orgs — hence the `OSSystems` prefix. +- `description` must be under 125 characters. +- `branding.icon` / `branding.color` are required to publish; keep them set. +- The publishing org must have 2FA enabled. diff --git a/docs/releasing.md b/docs/releasing.md new file mode 100644 index 0000000..ec09262 --- /dev/null +++ b/docs/releasing.md @@ -0,0 +1,31 @@ +# Releasing + +## Versioning + +Two kinds of tags, both on the same release commit: + +- `vX.Y.Z` (e.g. `v1.0.0`) — **immutable**. Matches a published Marketplace + release; never move it once published. +- `vX` (e.g. `v1`) — **movable major tag**. Most callers pin `@v1`, so it must + be fast-forwarded to each new release on the same major line. `v1` is a *tag*, + not a branch. + +## Cutting a new release + +1. Land all changes on `main`. +2. Tag the immutable version and push it: + ``` + git tag -a vX.Y.Z -m "vX.Y.Z" && git push origin vX.Y.Z + ``` +3. Move the major tag to the same commit: + ``` + git tag -f vX HEAD && git push -f origin vX + ``` +4. Create the GitHub release from the `vX.Y.Z` tag + (`gh release create vX.Y.Z --title vX.Y.Z --notes ...`). On the **first** + release of a major line, also check "Publish this Action to the GitHub + Marketplace" in the release UI (the Marketplace checkbox is UI-only) and + accept the Developer Agreement. + +For a docs/non-release change that should reach `@v1` callers without a new +version, just move the major tag: `git tag -f v1 HEAD && git push -f origin v1`.