Skip to content

Commit 5be96b8

Browse files
sgwannabeclaude
andcommitted
docs(contributing): commit-prefix semantic-scope convention (#71)
Adds a top-of-file Commit message convention section explaining: - release-please autobumps semver from Conventional Commits, so version prefixes (feat(v1.7.0): ...) are redundant and produce a CHANGELOG where every entry collapses under one synthetic version scope rather than the actual subsystem - Use semantic scope: feat(security), fix(cache), docs(readme), refactor(advocates), test(e2e), etc. - Allowed types map to release-please default ruleset - Suggested scope vocabulary covers the 18 main subsystems - Breaking-change syntax (! / BREAKING CHANGE: footer) Closes #71 part 1 (CONTRIBUTING). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
1 parent 6ac0f66 commit 5be96b8

1 file changed

Lines changed: 40 additions & 0 deletions

File tree

CONTRIBUTING.md

Lines changed: 40 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -4,6 +4,46 @@ Preview Forge introduces the **3-DD Methodology** (PreviewDD → SpecDD → Test
44
Contributions that strengthen any one of the three cycles, or that close
55
failure loops observed in real runs, are most welcome.
66

7+
## Commit message convention
8+
9+
This repo uses **release-please** with [Conventional Commits](https://www.conventionalcommits.org/).
10+
release-please **autobumps** semver from the commit history on every merge to
11+
`main`, so version-prefix scopes (`feat(v1.7.0): …`) are redundant — and they
12+
also make the resulting `CHANGELOG.md` harder to read because every entry
13+
collapses under one synthetic version scope instead of the actual subsystem.
14+
15+
**Use semantic scope, NOT version prefix:**
16+
17+
```
18+
Good: feat(security): reject traversal mockup_path + URL injection
19+
fix(cache): cmd_key empty-idea reject (T-9.1)
20+
docs(readme): add v1.6+ Socratic interview section
21+
refactor(advocates): extract py_sha256_file helper
22+
test(e2e): macOS CI matrix for verify-seed-expectations
23+
24+
Avoid: feat(v1.7.0): Phase 8 — Q-9 / Q-1 / Q-2
25+
fix(v1.X.Y): preview-cache hardening
26+
```
27+
28+
**Allowed types** (release-please default ruleset):
29+
30+
- `feat` — new behavior (minor bump)
31+
- `fix` — bug fix (patch bump)
32+
- `docs`, `refactor`, `test`, `chore`, `perf`, `ci`, `build` — no version bump
33+
34+
**Suggested scopes** (semantic, subsystem-oriented):
35+
36+
`security`, `cache`, `ideation`, `gallery`, `hooks`, `schema`, `advocates`,
37+
`monitors`, `bootstrap`, `panels`, `e2e`, `agents`, `memory`, `ci`,
38+
`profiles`, `scripts`, `commands`, `methodology`.
39+
40+
When a change cuts across many subsystems and a single scope is misleading,
41+
prefer no scope (`feat: …`) over a version scope.
42+
43+
**Breaking changes**: append `!` to the type/scope (`feat(profiles)!: …`)
44+
or include a `BREAKING CHANGE:` footer — release-please will pick it up
45+
for the major bump.
46+
747
## Local setup
848

949
```bash

0 commit comments

Comments
 (0)