Git & PR Conventions
Relevant source files
The following files were used as context for generating this wiki page:
The Vata project follows a strict set of Git and Pull Request (PR) conventions to ensure code quality, maintainable history, and efficient collaboration. The workflow emphasizes local-first development, English-only communication, and automated quality checks before any code is merged into the primary branch.
Sources: CLAUDE.md:162-164, README.md:1-10
Branching Strategy
The project mandates that no work is committed directly to the main branch. Every development task must ship as a Pull Request. Contributors must sync their local main with origin/main before starting any new branch or worktree.
Sources: CLAUDE.md:162, CLAUDE.md:175-182
Work Modes
Developers choose between two primary work modes based on the scope of the task:
| Mode | Use Case |
|---|---|
| Simple Branch | Single-file doc fixes, typos, or trivial config tweaks (estimated < 5 min). |
| Worktree | Multi-file changes (>3 files), new features, refactors, or long tasks likely to be interrupted. |
Sources: CLAUDE.md:166-173
Branch Naming
Branch names must follow a structured format aligned with conventional commits:
feat/<short-desc>: New featuresfix/<short-desc>: Bug fixesrefactor/<short-desc>: Code refactoringdocs/<short-desc>: Documentation updateschore/<short-desc>: Tooling or configuration changestest/<short-desc>: Testing-only changesperf/<short-desc>: Performance improvements
Sources: CLAUDE.md:197-205
Commit Standards
Vata uses Conventional Commits to maintain a readable and parsable project history. Commits should be granular, representing single, complete units of work that can be independently reverted.
Sources: CLAUDE.md:207-219
Commit Message Format
The project enforces specific prefixes for commit messages:
feat: add birth date picker to individual form
fix: prevent duplicate family relationships
refactor: extract date formatting to utility
test: add coverage for GEDCOM date parsing
Sources: CLAUDE.md:211-216
Pull Request Lifecycle
The PR process includes mandatory pre-review steps and automated quality enforcement via Git hooks and scripts.
Pre-PR Review Process
Before a PR is created, the following steps must be completed:
- Re-use/Quality Review: Run
/simplifyto analyze the branch diff for issues. - Local Review: Run
/reviewlocally to address findings. - Verification: Execute
pnpm verify, which runs linting, formatting checks, builds the project, and executes tests.
Sources: CLAUDE.md:231-236, package.json:33
Workflow Diagram
The following diagram illustrates the lifecycle of a task from branch creation to PR merge:
The workflow ensures that only verified code reaches the main branch and that resources are cleaned up post-merge.
Sources: CLAUDE.md:175-195, CLAUDE.md:221-229, package.json:33
Language and Documentation
All Git-related artifacts—including branch names, commit messages, and PR titles—must be written in English. This is part of a broader project requirement that includes all code (variable names, comments) and documentation.
Sources: CLAUDE.md:130-141
Automation and Project Setup
The repository includes a bootstrap script, scripts/setup-gh-project.sh, to standardize the GitHub environment. This script automates the creation of labels and project fields to support the PR workflow.
Automated Labels
The project uses specific labels to categorize issues and PRs:
| Label | Description |
|---|---|
individuals | People, names, and lifespan |
families | Spouse/parent/child links and pedigree |
gedcom | Import/export functionality |
infra | CI, scripts, and repo configuration |
good-first-issue | Suitable for newcomers |
Sources: scripts/setup-gh-project.sh:58-75
Git Hooks
Vata uses husky and lint-staged to enforce standards at the time of commit. This prevents improperly formatted code or linting errors from entering the repository.
Sources: package.json:47-51, package.json:89
Post-Merge Behavior
Once a Pull Request is merged, developers must:
- Call
ExitWorktree(if in worktree mode) to clean up session-registered worktrees. - Delete the local branch using
git branch -d <branch>. - Stop monitoring the PR: Do not push "nudge" commits or resurrect deleted branches.
Sources: CLAUDE.md:221-229
The conventions established here ensure that the Vata codebase remains stable and that the development history is clear, enabling a professional environment for contributors.