From 1dc86b9ff0d5775963a0bb081262174505b8e1c1 Mon Sep 17 00:00:00 2001 From: Rootiest Date: Mon, 31 Aug 2026 22:41:12 -0400 Subject: [PATCH] docs(contributing): document the WIP: title prefix for in-progress PRs MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Gitea treats a `WIP:` title prefix as a draft marker and refuses to merge while it's present. Verified empirically against this instance by temporarily retitling PR #123: the API flipped `draft` to true and `mergeable` to false, and both reverted when the prefix was removed. The distinction from the verification merge gate is the point, so it's stated explicitly in both files: `WIP:` means more code changes are coming, NOT "finished but unverified". A complete branch with unticked `## Verification` boxes is an ordinary PR — that case is already covered by the merge gate and does not want the prefix. The two signals are independent and can occur in any combination. Documented as a merge rule under Branching & Pull Requests, next to the verification gate, and in the template's title guidance where an author picking a title will actually encounter it. --- .github/PULL_REQUEST_TEMPLATE.md | 11 +++++++++++ CONTRIBUTING.md | 10 ++++++++++ 2 files changed, 21 insertions(+) diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 87fad7b..ef082b9 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -6,6 +6,17 @@ Types in use: feat, fix, docs, test, chore, perf, refactor, style. See CONTRIBUTING.md § Commit Conventions. + Still writing code? Prefix the title with `WIP:` — + WIP: feat(media): add play-media fzf picker + Gitea recognizes the prefix, marks the PR a draft, and blocks merging + until you remove it. The prefix goes before the whole conventional + subject, and comes off when the branch is complete. + + `WIP:` means MORE CHANGES ARE COMING. It is not for a finished branch + waiting on verification — that is what an unchecked box in Verification + already signals. A complete branch with open checkboxes is a normal PR, + not a WIP. + Keep the two headings below, in this order, and delete these comments. Optional sections may be added between them (see the note above "Verification"). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 586bd53..e36ddea 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -51,6 +51,16 @@ assumes you *do* have push access (maintainers, regular contributors). - **Don't merge until the `## Verification` checklist is fully checked.** Unchecked boxes are outstanding manual checks, not decoration. See [Pull request descriptions](#pull-request-descriptions) below. +- **Prefix in-progress PRs with `WIP:`.** If the branch still has code + changes coming, open it as `WIP: type(scope): description`. Gitea + recognizes the prefix, flags the PR as a draft, and refuses to merge it + until the prefix is removed; drop it once the branch is complete. + + `WIP:` signals **more changes are coming** — not "done but unverified". + A finished branch waiting on manual checks is an ordinary PR whose + `## Verification` boxes aren't all ticked yet; that's already the merge + gate above and doesn't need the prefix. The two are independent: a PR + can be WIP with everything ticked, or complete with checks outstanding. - **Keep feature branches focused.** If you stumble onto something unrelated to your current task while working (a pre-existing bug, a stray cleanup), don't fold it into the same commit or PR. Handle it with one of these,