docs(contributing): document the WIP: title prefix for in-progress PRs

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.
This commit is contained in:
2026-08-31 22:41:12 -04:00
parent ea8b13b38a
commit 1dc86b9ff0
2 changed files with 21 additions and 0 deletions
+11
View File
@@ -6,6 +6,17 @@
Types in use: feat, fix, docs, test, chore, perf, refactor, style. Types in use: feat, fix, docs, test, chore, perf, refactor, style.
See CONTRIBUTING.md § Commit Conventions. 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. Keep the two headings below, in this order, and delete these comments.
Optional sections may be added between them (see the note above Optional sections may be added between them (see the note above
"Verification"). "Verification").
+10
View File
@@ -51,6 +51,16 @@ assumes you *do* have push access (maintainers, regular contributors).
- **Don't merge until the `## Verification` checklist is fully checked.** - **Don't merge until the `## Verification` checklist is fully checked.**
Unchecked boxes are outstanding manual checks, not decoration. See Unchecked boxes are outstanding manual checks, not decoration. See
[Pull request descriptions](#pull-request-descriptions) below. [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 - **Keep feature branches focused.** If you stumble onto something unrelated
to your current task while working (a pre-existing bug, a stray cleanup), 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, don't fold it into the same commit or PR. Handle it with one of these,