CSE Roadmap

Specialist tier · about 5 hours · 13 parts

Part 5 of 13 · 2 min read

A project's own rules decide what gets merged, not general good practice

A perfectly reasonable commit message by your own standards can still be rejected for not matching a project's specific, stated convention.

Think of joining a new workplace with its own house style for memos: being a clear writer in general doesn't help if you ignore the specific template everyone there expects.

In plain words: a maintainer is the person with merge rights who decides what a project accepts, usually in their spare time, and a contributing guide (often CONTRIBUTING.md) states that project's own rules for issues, branches, tests, style and review -- including sometimes requiring a sign-off line (Signed-off-by:, added by git commit -s) as a statement that you have the right to submit the change -- so following the project's own stated rules, not general convention, is what a checker and a maintainer actually look for.

A worked example. The "no-test" branch's commit message, "Fixed parsing," is flagged by the commit checker for not being imperative -- a maintainer following common convention expects "Fix parsing," because the subject line should read as an instruction, not a report of something already done. The "good" branch's commit subject and the description "Fixes #123" style issue-linking pattern pass cleanly, because they match what the checker -- standing in for a maintainer's expectations -- is looking for.

The key lines. From code/mini-pr/prcheck.py:

# from code/mini-pr/prcheck.py
PAST = re.compile(r"^(fixed|fixes|added|adds|updated|updates|changed|changes|removed|removes|fixing|adding|updating)$", re.I)

Read it as: the regex is a specific, limited whitelist of past-tense and -ing verb forms, matched against only the first word of the subject line. This single pattern enforces one house-style convention (imperative mood). That is one project's own rule stated as a regex. A different project's CONTRIBUTING.md could require something else entirely. The checker would then need its own different rule to match it.

CONTRIBUTING file, sign-off, maintainer

The contributing guide (often CONTRIBUTING.md) is the project's rules for issues, branches, tests, style and review. A sign-off is a Signed-off-by: line in a commit message, added by git commit -s, which some projects require as a statement that you have the right to submit the change. A maintainer is a person with merge rights who decides what the project accepts, usually in their spare time.

Example: "Fixed parsing" failing the imperative-mood check is a small thing by itself, but it's a concrete instance of the general rule: a maintainer's attention is the scarce resource, and a commit message that doesn't match their project's stated convention is one more thing they have to ask you to change before they can merge.