From 1eec71ded1513f857279ca0644b21795a8cc64c9 Mon Sep 17 00:00:00 2001 From: Kareem Horstink Date: Sun, 26 Jul 2026 14:22:44 +0000 Subject: [PATCH] docs: add conventional commits guide and design decisions template --- CONTRIBUTING.md | 99 ++++++++++++++++++++++++++++++++++++++++++++++++- DESIGN.md | 33 +++++++++++++++++ 2 files changed, 131 insertions(+), 1 deletion(-) create mode 100644 DESIGN.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index d4769a7..1480a65 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,9 +18,47 @@ ### Git Workflow - Small, focused commits with descriptive messages -- Branch naming: `feature/`, `bugfix/` +- Branch naming: `feat/`, `chore/`, `bugfix/` - Pull requests should include what/why, not just what changed +#### Conventional Commits + +Use this format for all commit messages: + +``` +: +``` + +**Types:** + +| Type | When to use | +|-----------|------------------------------------------------------| +| `feat` | New feature or functionality | +| `fix` | Bug fixes | +| `chore` | Maintenance, docs, config, dependencies | +| `refactor`| Code change that neither fixes a bug nor adds a feat | +| `test` | Adding or updating tests | +| `docs` | Documentation changes only | +| `style` | Formatting, whitespace, semicolons (no code change) | +| `perf` | Performance improvements | + +**Examples:** + +``` +feat: add player movement with WASD and mouse look +fix: resolve collision detection issue on river logs +chore: update README with setup instructions +docs: add game design questionnaire +refactor: extract enemy AI into separate class +perf: optimize physics process loop +``` + +**Rules:** + +- Lowercase description after the colon +- No period at the end +- Imperative mood: "add" not "added" or "adds" + ## AI Development Guidelines When working with AI assistants on this project: @@ -29,6 +67,65 @@ When working with AI assistants on this project: 2. **Godot patterns** — AI should follow Godot 4 C# conventions (signals, `_Process`, `_PhysicsProcess`, etc.) 3. **Incremental changes** — one feature at a time; verify each works before moving on 4. **Scene integrity** — don't modify `.tscn` files directly unless necessary; prefer code-based node creation +5. **C#优先** — implement as much as possible in C# rather than GDScript or visual scripting + +## AI Development Cycle + +All feature work follows this cycle: + +``` +┌─────────────────────────────────────────────────────────────┐ +│ 1. PLAN CHANGES │ +│ - Describe what will be built, why, and how │ +│ - List files to create/modify │ +│ - Note any design decisions │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 2. REVIEW CHANGES (initial) │ +│ - Self-review before implementation │ +│ - Check against design doc and questionnaire │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 3. PRESENT CHANGES │ +│ - Show what you plan to do │ +│ - Await feedback/approval │ +└─────────────────────────────────────────────────────────────┘ + ↓ (feedback → loop back to Plan) + ↓ (approved) +┌─────────────────────────────────────────────────────────────┐ +│ 4. IMPLEMENT CHANGES │ +│ - Write code, create scenes, update docs │ +│ - Keep changes focused and atomic │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 5. REVIEW CHANGES (fresh perspective) │ +│ - Use a fresh subagent or second pass without bias │ +│ - Check for bugs, style issues, Godot best practices │ +└─────────────────────────────────────────────────────────────┘ + ↓ (issues → loop back to Implement) + ↓ (approved) +┌─────────────────────────────────────────────────────────────┐ +│ 6. PRESENT FINAL CHANGES │ +│ - Show completed implementation │ +│ - Summarize what was done │ +└─────────────────────────────────────────────────────────────┘ + ↓ +┌─────────────────────────────────────────────────────────────┐ +│ 7. DOCUMENT DESIGN CHOICES (if applicable) │ +│ - Update DESIGN.md with key decisions │ +│ - Note trade-offs, alternatives considered │ +└─────────────────────────────────────────────────────────────┘ +``` + +### Key Rules + +- **Never skip review** — even small changes get a second look +- **Fresh eyes matter** — use a different agent/context for the final review when possible +- **Feedback is mandatory** — if feedback requests changes, loop back to Plan +- **Document decisions** — if a design choice was made, record it in `DESIGN.md` ## Quick Reference diff --git a/DESIGN.md b/DESIGN.md new file mode 100644 index 0000000..2e625de --- /dev/null +++ b/DESIGN.md @@ -0,0 +1,33 @@ +# FrogFPS — Design Decisions Log + +*Track important design choices here. Each entry explains what was decided, why, and any alternatives considered.* + +--- + +## Template + +```markdown +### [Date] — [Feature/Decision Name] + +**Decision:** What was chosen + +**Rationale:** Why this choice was made + +**Alternatives Considered:** +- Option A: ... +- Option B: ... + +**Trade-offs:** +- Pros: ... +- Cons: ... + +**Related Files:** +- `path/to/file.cs` +- `path/to/scene.tscn` +``` + +--- + +## Entries + +