diff --git a/.github/pull_request_template.md b/.github/pull_request_template.md index 8a19ec8..1062149 100644 --- a/.github/pull_request_template.md +++ b/.github/pull_request_template.md @@ -1,8 +1,11 @@ + an H1 renders oversized in one. The title becomes the squash subject with + ` (#N)` appended, so write it as a Conventional Commit: imperative, + lowercase, and short enough that the subject is still 50 characters or + fewer once the number is on it. `gitlint` enforces that bound on every + local commit but never sees the merged subject, so this is the one place + it has to be kept by hand. --> ## What changes, and why diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a382ffb..cd532ce 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -84,7 +84,7 @@ The hook and the action share the CLI and nothing else. A green test suite says Fork, branch, and open a pull request; `main` takes no direct pushes. A pull request merges once it has one approving review, every review thread resolved, and the required contexts green. Squash is the only merge method enabled, which is why the title matters below. -Conventional Commit messages; imperative, lowercase subjects of 50 characters or fewer. Commit atomically — one concern per commit. Pull request titles become the squash subject, so write them the same way. +Conventional Commit messages; imperative, lowercase subjects of 50 characters or fewer. Commit atomically — one concern per commit. Pull request titles become the squash subject with a space and `(#N)` appended, so write them the same way and short enough that the subject is still 50 characters or fewer once the number is on it. `coverage` is deliberately not a required context — it mints its credential through OIDC, which a pull request from a fork cannot be granted, so requiring it would block outside contribution permanently. And a commit whose author email is not linked to your GitHub account asks for a second approval, under a rule that gives no reason on the page; linking the address in your account settings clears it. diff --git a/corpus/README.md b/corpus/README.md index 0a4c792..d052efe 100644 --- a/corpus/README.md +++ b/corpus/README.md @@ -56,4 +56,6 @@ Idempotency matters most in practice: a formatter that keeps rewriting the same Write the three files and it is picked up automatically; nothing registers cases by name. Prefer a case that pins one decision, and put the argument in `why` rather than in the slug — the slug becomes the test id, and the `why` is what the next person needs when they are staring at a failure and deciding whether the rule or the case is wrong. +Produce `expected.md` by running the tool over `input.md` and reading the diff, rather than by writing it out, and never edit one to make a test pass: an answer key written by hand pins what its author believed, which is the one thing a conformance case must not do. This tier has no regeneration command — `REGENERATE_CLI_CORPUS` belongs to the CLI tier and does not reach it — so nothing but the discipline enforces that here, which is why it is worth stating in the tier that lacks the tooling rather than only in the one that has it. + A case whose expected output equals its input is not a wasted case. Most of this tool is the part that declines to act, and those are exactly the cases a change is most likely to break.