diff --git a/plugins/gitea/docs/research/docs/gitea/sources.md b/plugins/gitea/docs/research/docs/gitea/sources.md index f2600e5..2abbf0d 100644 --- a/plugins/gitea/docs/research/docs/gitea/sources.md +++ b/plugins/gitea/docs/research/docs/gitea/sources.md @@ -20,3 +20,17 @@ - **Description:** Gitea REST API swagger documentation covering underlying endpoints for issues, PRs, labels, milestones, and branches - **Contributing files:** (see notes below) - **Status:** `no content extracted` — source fetch timed out; all reference content derived from gitea-mcp source files which are authoritative for MCP tool usage + +## context7-websites-gitea + +- **URL:** context7:/websites/gitea +- **Description:** Official Gitea docs mirror on Context7 (docs.gitea.com content) — scoped/exclusive label conventions, branch protection and PR review/merge rules, release and webhook semantics, issue/PR automatic cross-reference linking. Backfills the external/best-practice gap left by the original docs.gitea.com fetch timeout. +- **Contributing files:** workflow-conventions.md +- **Status:** `extracted` + +## context7-gitea-tea-cli + +- **URL:** context7:/git_gitea_com/gitea_tea +- **Description:** Official `tea` CLI (reference Gitea client) docs on Context7 — practitioner command patterns for issues, PRs, and releases, including semver tag/release conventions, draft/prerelease flags, and release-notes-from-file conventions. +- **Contributing files:** workflow-conventions.md +- **Status:** `extracted` diff --git a/plugins/gitea/docs/research/docs/gitea/workflow-conventions.md b/plugins/gitea/docs/research/docs/gitea/workflow-conventions.md new file mode 100644 index 0000000..c27a680 --- /dev/null +++ b/plugins/gitea/docs/research/docs/gitea/workflow-conventions.md @@ -0,0 +1,88 @@ +--- +topic: workflow-conventions +source_keys: + - context7-websites-gitea + - context7-gitea-tea-cli +--- + +# Gitea Workflow Conventions + +Practitioner conventions and platform behavior that inform *how* to use the mechanics already +documented in `api-reference.md` — not additional tool schemas. + +## Scoped, exclusive labels + +Gitea labels support a scoped-label convention: a `/` delimiter in the label name (e.g. +`Priority/High`) plus an `exclusive: true` flag means only one label from that scope can be applied +to an issue or PR at a time — applying a new `Priority/*` label automatically replaces the previous +one. This is exactly the `Kind/*` / `Priority/*` / `Status/*` taxonomy already used in this repo's +own label set, confirming the taxonomy follows Gitea's native scoped-label convention rather than an +ad hoc naming scheme. When defining or inferring labels, a scope prefix implies mutual exclusivity — +label inference logic should replace, not add to, existing labels in the same scope. + +Repositories can also seed a predefined label set at creation time from a YAML label file +(`name`, `color`, `description`, `exclusive`), which is where the base `Kind/Priority/Status` sets +typically originate. + +## Milestone and label state as first-class transitions + +Both issues and PRs treat labeling and milestoning as discrete state-transition events +(`label_updated`/`label_cleared`, `milestoned`/`demilestoned`), not passive metadata fields. This +reinforces treating `gitea-labels-milestones` as a shared skill: the same transition semantics apply +whether the target is an issue or a PR. + +## Automatic cross-reference linking + +Gitea auto-renders issue/PR references in body text without any API call: `#1234` and `!1234` both +resolve to issue/PR 1234 in the same repo (issues and PRs share one number space, consistent with +`data-model.md`); cross-repo references use `owner/repo#1234` (issue) or `owner/repo!1234` (PR). This +directly validates the dependency-linking convention decided for `gitea-issues` (issue #6, comment +#848): writing `Depends on #N` in an issue body is not just a text convention — Gitea renders it as +a real clickable cross-reference automatically, with no separate API call required. For +external-issue-tracker repos, the same syntax renders as an external link instead, so the skill +should assume same-repo internal linking unless told otherwise. + +## Pull request review workflow + +The reviewer flow is: comment, request changes, or approve; the author pushes updates to the same +branch, which the PR auto-tracks; maintainers merge once approved. Protected branches can layer +additional constraints on top of this base flow: + +- An allowlist of users/teams may be required to approve before merge is possible. +- A minimum approval count can be enforced. +- Stale approvals (approvals given before new commits were pushed) can be auto-dismissed or ignored. +- Merge can be blocked if any review requests changes, if requested reviewers haven't reviewed yet, + or if the branch is outdated relative to its base. +- Repository admins are not exempt from these rules by default — an explicit + "administrators must follow branch protection rules" setting is what removes their force-merge + bypass. + +A skill that merges PRs should treat "CI passing" and "reviews satisfied" as two independently +checkable gates — `get_status` covers CI, but review/approval state and branch-protection +constraints are a separate check the merge call itself will enforce server-side and return as an +error if unmet. + +## Release and tag conventions + +Releases are conceptually separate from tags but always tied to one: a release wraps a tag with a +title, notes, and optional binary assets. Practitioner convention (per the `tea` CLI, the reference +Gitea client) is: + +- Tag names are semver-style, typically `v`-prefixed (`v1.2.0`, `v2.0.0-beta.1`). +- Release notes are commonly sourced from a changelog file rather than typed inline. +- Draft and prerelease are separate boolean flags, not states inferred from the tag name — a + prerelease is anything with a `-beta`/`-rc` style suffix by convention, but Gitea does not enforce + this; the skill should treat `draft`/`prerelease` as flags the caller sets explicitly rather than + something to infer from the tag string. +- Deleting a release does not delete its tag by default — the two are separate destructive + operations (confirmed by `delete_release` taking a numeric release ID per `troubleshooting.md`, + distinct from `delete_tag`). + +## File editing: direct commit vs. PR + +Gitea's own UI defaults to prompting for a target branch when creating/editing a file directly +through the web interface, and supports pre-filling a new file's path and content via query +parameters — reflecting that direct-commit file edits are a first-class, expected workflow (not just +an API escape hatch). This supports `create_or_update_file`/`delete_file` being used directly against +a working branch as a normal editing action, with the SHA-currency requirement (`troubleshooting.md`) +being the main gotcha rather than direct-commit being an anti-pattern to avoid.