Vaessl/docs/CONVENTIONS.md

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:

<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