From dfacf051a8d0d28a37cae44faa644ffe86f2db8c Mon Sep 17 00:00:00 2001 From: Defame1297 Date: Sun, 30 Aug 2026 12:06:37 +0000 Subject: [PATCH] refactor(gitea-releases): retrofit to the ADR-0020 context contract Description 500 -> 211 chars, body 676 -> 462 words, Gotchas 5 entries/41% of body -> 3/21%. Clears the description FAIL and both Gotchas suggestions. Cut the second trigger register (the re-quoted user phrasings), the doubled capability enumeration across releases and tags, and the gitea-issues/gitea-prs boundary, which defended against nothing -- neither was going to win a release request. Kept the indirect trigger and the one real near-miss, gitea-branches. Releases and tags are one flow, not two: 'delete the release and its tag' is a single invocation that takes both branches, which disqualifies mutual exclusivity, so no dispatch split. Two Gotchas moved to references/ behind explicit triggers; one deleted as a paraphrase of the step below it. Refs #99 --- .../gitea/.apm/skills/gitea-releases/SKILL.md | 29 ++++++++----------- .../gitea-releases/references/sources.md | 3 +- 2 files changed, 13 insertions(+), 19 deletions(-) diff --git a/plugins/gitea/.apm/skills/gitea-releases/SKILL.md b/plugins/gitea/.apm/skills/gitea-releases/SKILL.md index 7bcc8e9..a573c4c 100644 --- a/plugins/gitea/.apm/skills/gitea-releases/SKILL.md +++ b/plugins/gitea/.apm/skills/gitea-releases/SKILL.md @@ -2,12 +2,9 @@ name: gitea-releases description: > - Use when managing Gitea releases and tags for a repository: listing, creating, or deleting - releases (with draft/prerelease flags and release notes), and listing, creating, or deleting the - underlying git tags. Use even if the user doesn't say "release" explicitly — "cut a v1.2.0", - "publish a prerelease", "tag this commit", or "what's the latest release" all apply. Do not use - for git branch or commit history operations (use gitea-branches) or for issue/PR management (use - gitea-issues / gitea-prs). + Use when managing Gitea releases or the git tags underneath them — list, get, + create, or delete either — even when the user does not say "release" or + "Gitea". Not branches or commit history -> `gitea-branches`. metadata: category: gitea @@ -20,11 +17,9 @@ metadata: ## Gotchas -- **`delete_release` takes a numeric `id`, never a tag name.** `delete_tag` is the mirror opposite — it takes the `tag_name` string, never a numeric id. These two tools are asymmetric on purpose; passing a tag name to `delete_release` or a numeric id to `delete_tag` fails. Always resolve the numeric release id via `list_releases` or `get_release` first if you only have a tag name in hand. -- **Deleting a release does not delete its tag.** They are separate destructive operations against separate resources — a release is a wrapper (title, notes, draft/prerelease flags, assets) around a tag, not the tag itself. If the intent is to remove both, call `delete_release` and `delete_tag` separately. -- **`list_releases`/`list_tags` default to `per_page: 20`**, unlike most other gitea-mcp tools which default to 30. The MCP layer does no auto-pagination — to get a complete result set, loop `page` upward until a page returns fewer than `per_page` results. -- **`is_draft`/`is_pre_release` are explicit booleans the caller sets on `create_release` — never inferred from `tag_name`.** Note the input param is `is_draft`, which maps to the `draft` field on the *response* object (see Dispatch table below and `references/call-signatures.md`) — `draft` is never a valid input key. Practitioner convention (per the `tea` CLI) uses `-beta`/`-rc` suffixes for prereleases (e.g. `v2.0.0-beta.1`), but Gitea does not enforce or infer this from the tag string. If the user names a tag that looks like a prerelease, set `is_pre_release: true` explicitly rather than assuming the flag is redundant with the name. -- **Tag names are conventionally semver, `v`-prefixed** (`v1.2.0`, `v2.0.0-beta.1`), but this is a practitioner convention, not a Gitea constraint — don't reject or rewrite a caller-supplied tag name that doesn't follow it. +- **Deleting a release never deletes its tag, and deleting a tag never deletes the release wrapping it.** A release is a metadata wrapper around a tag, so removing both takes two independent destructive calls. +- **`is_draft`/`is_pre_release` are booleans the caller sets — Gitea never infers a prerelease from a `-beta`/`-rc` tag name.** The response object names them `draft`/`prerelease`; passing `draft` as an input key is silently ignored, not rejected. +- **`list_releases`/`list_tags` default `per_page` to 20**, where most other gitea-mcp list tools default to 30 — a caller assuming 30 under-counts the pages a full sweep needs. ## Dispatch table @@ -40,13 +35,13 @@ metadata: | Create tag | `create_tag` | `owner`, `repo`, `tag_name` | `target`, `message` | | Delete tag | `delete_tag` | `owner`, `repo`, `tag_name` | — | -`target` (on `create_release`/`create_tag`) is a commitish — a branch name, existing tag, or commit SHA — the point the new tag is cut from. See `references/call-signatures.md` for response shapes. +`target` (on `create_release`/`create_tag`) is a commitish — a branch name, existing tag, or commit SHA — the point the new tag is cut from. ## Workflow -- [ ] **Creating a release:** Call `create_release` directly with `tag_name` + `target` + `title` — Gitea is assumed to create the underlying tag automatically if `tag_name` doesn't already exist (this is plausible behavior inferred from the API shape, not directly confirmed in the research docs), so a separate `create_tag` call is only needed when you want to tag a commit without wrapping it in a release yet. Verify the tag exists afterward if this matters to the caller. Set `is_pre_release`/`is_draft` explicitly per the Gotchas above; don't leave them to default inference. -- [ ] **Deleting a release safely:** Resolve the numeric id first — call `list_releases` (paginate if needed, see Gotchas) or `get_release` if the id is already known, find the entry matching the target `tag_name`, then call `delete_release` with that `id`. Never pass `tag_name` to `delete_release`. -- [ ] **Deleting a tag along with its release:** Delete the release first (frees the id lookup), then call `delete_tag` with the `tag_name` separately — confirm both are intended before proceeding, since each is an independent irreversible operation. -- [ ] **Listing every page:** If the caller needs all releases or tags (not just the first page), loop `page: 1, 2, 3...` until a response has fewer than `per_page` entries. +- [ ] **Creating a release:** Call `create_release` with `tag_name`, `target`, and `title`. Gitea is assumed to create the tag from `target` when `tag_name` does not yet exist — plausible from the API shape, not confirmed in the research docs — so a separate `create_tag` is only needed to tag a commit without wrapping it in a release. Verify with `get_tag` afterward if the caller depends on it. +- [ ] **Deleting a release:** `delete_release` takes the numeric `id` and never a `tag_name`; `delete_tag` is the mirror opposite and never takes an id. With only a tag name in hand, resolve the id through `list_releases` (paginating if needed) or `get_release` first. +- [ ] **Deleting a tag along with its release:** Delete the release first, then call `delete_tag` — confirm both are intended before proceeding, since each is irreversible on its own. +- [ ] **Listing every page:** Loop `page: 1, 2, 3...` until a response returns fewer than `per_page` entries. Nothing here auto-paginates. -If exact response field shapes or additional conventions are needed, read `references/call-signatures.md` and `references/conventions.md`. +If exact input params or response field shapes are needed, read `references/call-signatures.md`. If the caller raises semver tag naming, release-notes sourcing, or how a release relates to its tag, read `references/conventions.md`. diff --git a/plugins/gitea/.apm/skills/gitea-releases/references/sources.md b/plugins/gitea/.apm/skills/gitea-releases/references/sources.md index 2b67a9f..cffb8b9 100644 --- a/plugins/gitea/.apm/skills/gitea-releases/references/sources.md +++ b/plugins/gitea/.apm/skills/gitea-releases/references/sources.md @@ -42,7 +42,6 @@ - **Research doc:** plugins/gitea/docs/research/docs/gitea/workflow-conventions.md (Release and tag conventions section) **Contributing files:** -- SKILL.md (Gotchas — semver tag naming) -- references/conventions.md +- references/conventions.md (semver tag naming, release-notes sourcing) **Status:** `extracted`