Defame1297
fdeaf741a8
Covers releases and tags (list/get/create/delete) — all verified working with the current write:issue/write:repository token scope.
1.8 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
draft and is_pre_release/prerelease 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.
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.