Defame1297
d2da45f78c
The retrofit left only a descriptive sentence on the loaded path — "Gitea never infers a prerelease from a -beta/-rc tag name" — and moved the imperative into references/conventions.md behind a trigger listing semver naming, release-notes sourcing and release-to-tag relationships. Draft and prerelease are not in that list, and "cut a v2.0.0-beta.1" is exactly the request where the caller does not raise the topic, so the rule was unreachable from the flow that needs it. Severity comes from the repair path: the MCP surface has create, get, get_latest, list and delete only — there is no update or edit tool. A release published without is_pre_release can only be corrected by delete_release plus a fresh create, and get_latest_release points consumers at the beta meanwhile. Neither SKILL.md nor call-signatures.md said so anywhere. The flags are now set explicitly on every create, the missing update tool and its delete-and-recreate consequence are stated in the body, and the semver pass-through rule stranded behind the same trigger is promoted alongside it. call-signatures.md now cites the deployed tool description as direct evidence that get_latest_release excludes drafts, while keeping the prerelease half hedged — that remains unconfirmed. Verified live against gitea-mcp v1.7.0, read-only calls. Refs #99
2.6 KiB
topic, source_keys
| topic | source_keys | ||
|---|---|---|---|
| conventions |
|
Release and tag conventions
Practitioner conventions that inform how to use the mechanics in call-signatures.md — not
additional tool schemas.
Release wraps a tag, not the reverse
A release is a title, body (notes), and draft/prerelease flags layered on top of an existing or
newly-created tag. The tag is the git-level object (a name pointing at a commit); the release is a
Gitea-level metadata wrapper around it. This is why delete_release and delete_tag are separate
calls with separate identifiers (numeric id vs. tag name) — removing the wrapper never implies
removing the underlying pointer, and vice versa.
Semver tag naming
Per the tea CLI (the reference Gitea client), tag names conventionally follow semver with a v
prefix: v1.2.0, v2.0.0-beta.1. This is a convention observed by tooling and humans, not a
Gitea-enforced constraint — the API accepts any string as tag_name. Don't validate or rewrite a
caller-supplied tag name against semver; just pass it through.
Draft and prerelease are explicit flags
is_draft and is_pre_release are booleans the caller sets directly on create_release — Gitea
does not infer either from the tag name, even though the -beta/-rc suffix convention above is
commonly used to signal a prerelease to humans. When a user asks to "cut a beta" or "publish a
release candidate," set is_pre_release: true explicitly in the same call rather than relying on
the tag string to carry that meaning.
Getting this wrong is not cheaply repairable. The gitea-mcp release surface is create_release,
get_release, get_latest_release, list_releases and delete_release — there is no update or
edit tool, so a published release's flags cannot be corrected in place. The only remedy is
delete_release plus a fresh create_release, a destructive round trip; meanwhile a beta published
without is_pre_release is the release get_latest_release returns. Set the flags in the create
call.
Note the input/output naming mismatch: the input param is is_draft, but the release object
returned by the API uses draft (and prerelease) as the field names. draft is never a valid
input key — passing draft: true to create_release is silently ignored rather than erroring.
Release notes sourcing
Practitioner convention (per tea) is to source release notes (body) from a changelog file
rather than typing them inline for each release — useful context when a caller asks to "generate"
or "use the changelog for" release notes rather than write them from scratch.