rootiest
1dc86b9ff0
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.
110 lines
4.9 KiB
Markdown
110 lines
4.9 KiB
Markdown
<!--
|
|
PR title: Conventional Commits — type(scope): description
|
|
e.g. fix(mv): bring header and completions up to repo conventions
|
|
Lowercase after the colon, imperative mood, no trailing period.
|
|
Append `!` after the scope for a breaking change: feat(logging)!: ...
|
|
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").
|
|
-->
|
|
|
|
## Summary
|
|
|
|
<!--
|
|
What changed and why. A short prose paragraph, 2-5 bullets, or a
|
|
paragraph followed by bullets — whichever fits the change.
|
|
|
|
- Name concrete paths and identifiers in backticks (`functions/mv.fish`,
|
|
`$__fish_config_op_autoexec`), not vague descriptions.
|
|
- Lead a bullet with a **bold phrase** when it covers a distinct file or
|
|
behavior, so the list scans at a glance.
|
|
- Explain the reasoning, not just the diff — a reader should understand
|
|
why this approach over the obvious alternative.
|
|
- Say so explicitly when there is no behavioral change, when a file is
|
|
generated by the docs pipeline, or when the change is scoped to the
|
|
site build only.
|
|
|
|
If this PR resolves a tracked issue, close it with a trailing line at the
|
|
end of this section — not at the very bottom, since Verification is
|
|
always last:
|
|
|
|
Closes #42
|
|
|
|
Gitea and GitHub both auto-close the issue on merge. `Fixes #N` and
|
|
`Resolves #N` work identically; pick whichever reads correctly. Use one
|
|
line per issue (`Closes #42, closes #43` — the keyword must be repeated,
|
|
a bare `#43` after a comma is only a link and will NOT close). For an
|
|
issue that is related but should stay open, reference it without a
|
|
keyword: `Refs #42`. Omit all of this entirely when no issue is involved
|
|
— do not leave an empty `Closes #` behind.
|
|
-->
|
|
|
|
<!--
|
|
OPTIONAL SECTIONS — add any `##` heading here that the change actually
|
|
needs, and skip them entirely for a straightforward one. Used in this
|
|
repo, roughly in order of frequency:
|
|
|
|
## Root cause — for a bug fix, what was actually wrong
|
|
## Why — motivation, when it isn't obvious
|
|
## How it works — mechanism, for a non-trivial new feature
|
|
## Behavior — user-visible behavior before/after
|
|
## Changes — a longer breakdown than Summary can carry
|
|
## Docs — documentation touched by this change
|
|
## Notes — caveats, follow-ups, deferred work
|
|
## Scope note — what this deliberately does NOT cover
|
|
## Opinionated guard (C1-C6)
|
|
— which tier gates this, and behavior when off
|
|
## ⚠️ Breaking Change — required whenever the title carries `!`;
|
|
state the break and the migration path
|
|
|
|
A "Why not <alternative>?" heading is also common when a reviewer would
|
|
reasonably ask why the obvious approach was rejected.
|
|
-->
|
|
|
|
## Verification
|
|
|
|
<!--
|
|
Every check this change needs, as a checkbox list. Always the last
|
|
section.
|
|
|
|
A CHECKED box means verified — either it ran programmatically (test
|
|
suite, linter, docs verifier, CI) or the author performed it by hand and
|
|
confirmed the result. Check these off before opening the PR.
|
|
|
|
An UNCHECKED box is an outstanding manual check the reviewer still has to
|
|
perform. Leave anything you could not verify yourself unchecked rather
|
|
than dropping it, so it stays visible.
|
|
|
|
**This list is the merge gate: the PR does not merge until every box is
|
|
checked.** So only put things here that can actually be resolved — a
|
|
check nobody is able to run blocks the PR forever. Genuinely unverifiable
|
|
caveats, assumptions, and known limitations belong in a `## Notes`
|
|
section instead, where they inform the review without gating it.
|
|
|
|
- One check per line, imperative, with the exact command in backticks
|
|
and the expected result stated.
|
|
- Cover the regression path, not just the happy path: the old behavior
|
|
still working, the opinionated toggle disabled, the error branch.
|
|
- Include the repo's standing gates when the change touches what they
|
|
guard: `fish -n <file>`, `fish_indent`, `python3 docs/verify-manual.py`,
|
|
`python3 docs/build-manual.py --site`, `fish tests/run-tests.fish`.
|
|
- Reset any universal variable you set during a check.
|
|
-->
|
|
|
|
- [ ]
|
|
- [ ]
|