docs: add git and ticket conventions

2026-07-21 01:36:24 +02:00
parent b08fbf3b03
commit 5f4f417edc
1 changed files with 61 additions and 0 deletions
@@ -0,0 +1,61 @@
+# Git Conventions
+
+## Branch Naming
+
+```
+<type>/<short-kebab-case-description>
+```
+
+- All lowercase, hyphens only — no camelCase or Title-Case
+- Keep the description short (3–5 words); the branch name is not the place for detail
+- If using a ticket tracker, include the ID: `feature/VAE-123-ai-search`
+
+| Type | Use for |
+|---|---|
+| `feature/` | New functionality |
+| `fix/` | Bug fixes |
+| `refactor/` | Code changes with no behavior change |
+| `chore/` | Tooling, deps, config, cleanup |
+| `docs/` | Documentation only |
+
+**Example:** `feature/ai-search`
+
+---
+
+## Commit Messages
+
+Follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+```
+<type>(<scope>): <imperative, present-tense summary>
+
+<optional body — explain WHY, not WHAT>
+```
+
+- **Type** — same list as branch types above, plus `test`, `style`
+- **Scope** — the module/package touched (e.g. `search`, `sync`, `connection`, `vector`, `frontend`)
+- **Summary** — imperative mood ("add", not "added" or "adds"); no period at the end
+- **Body** — only when the reasoning isn't obvious from the diff (a constraint, a bug workaround, a decision). Skip it for simple/self-explanatory changes.
+
+**Examples:**
+```
+feat(search): route SearchRequest.aiSearch to AI provider map
+fix(sync): prune stale vectors only after full page loop completes
+style: reformat
+refactor(vector): nest extraData by section for clearer embedding
+```
+
+---
+
+## Ticket Titles
+
+Frame as the outcome, not a task log:
+
+```
+<Type>: <what changes for the user/system>
+```
+
+**Examples:**
+- `Feature: Add AI-powered search to Homebox connector`
+- `Bug: /api/sync not triggered on login`
+- `Chore: Consolidate SearchService provider maps`