Document PR title and description conventions #14

Merged

arne merged 1 commit from docs/pr-conventions into main

2026-04-05 21:53:08 +02:00

arne commented

2026-04-05 21:49:23 +02:00

Owner

The repo's git conventions in CLAUDE.md encouraged conventional-commit
prefixes (feat:, fix:, chore:) on PR titles, but as orbit has grown
those prefixes have started reading as clutter — they add technical
noise without telling a reader anything about what actually changed. The
History stage on orbit itself makes this concrete: a row that says
feat: pull request tracking and Claude removal is worse to scan than
one that says Show open pull requests in the Review stage.

This PR drops the prefix guidance and adds a short section covering title
and description structure. Titles should describe what orbit can do now,
active voice, plain English. Descriptions should open with the problem,
use subheadings for bundled concerns, and keep scope-boundary notes
(Known cuts, Follow-ups) at the bottom.

No code changes, no behavior changes. Documentation-only, so the
convention is in the repo before the backlog of older PRs gets rewritten
by hand to match.

Follow-ups

Rewrite titles and descriptions on the previously-merged PRs
(Orbit MVP through #13) to serve as in-repo examples of the new
convention.
Normalize commit author email on the three commits made from local
git config (arnefismen@gmail.com → arne@fismen.net) during the
rewrite.
Consider a semantic taxonomy later (labels, History stage categories)
once a few more PRs have landed under the new convention.

The repo's git conventions in `CLAUDE.md` encouraged conventional-commit prefixes (`feat:`, `fix:`, `chore:`) on PR titles, but as orbit has grown those prefixes have started reading as clutter — they add technical noise without telling a reader anything about what actually changed. The History stage on orbit itself makes this concrete: a row that says `feat: pull request tracking and Claude removal` is worse to scan than one that says `Show open pull requests in the Review stage`. This PR drops the prefix guidance and adds a short section covering title and description structure. Titles should describe what orbit can do now, active voice, plain English. Descriptions should open with the problem, use subheadings for bundled concerns, and keep scope-boundary notes (`Known cuts`, `Follow-ups`) at the bottom. No code changes, no behavior changes. Documentation-only, so the convention is in the repo before the backlog of older PRs gets rewritten by hand to match. ## Follow-ups - Rewrite titles and descriptions on the previously-merged PRs (`Orbit MVP` through #13) to serve as in-repo examples of the new convention. - Normalize commit author email on the three commits made from local git config (`arnefismen@gmail.com` → `arne@fismen.net`) during the rewrite. - Consider a semantic taxonomy later (labels, History stage categories) once a few more PRs have landed under the new convention.

arne added 1 commit

2026-04-05 21:49:23 +02:00

Document PR title and description conventions a8d78334b5

Drop the conventional-commit prefix guidance in favor of plain-English
titles that describe what orbit can do now, and add a structure section
for descriptions (problem first, subheadings for bundled concerns,
known-cuts and follow-ups at the bottom). The existing feat:/fix:/chore:
line contradicted the new guidance and is removed.