2.1 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.
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.