Owner: Engineering Team | Last Updated: 2026-01-30 | Status: Current
This page defines the WWAI Git branching strategy, commit conventions, pre-commit hooks, pull request process, and deployment pipeline. All contributors must follow these standards to maintain a clean, auditable history and reliable CI/CD flow.
The workflow follows a two-branch trunk model: main represents production, dev serves as the integration branch, and all work happens on short-lived topic branches that merge into dev via pull request.
main ─────────────────────●──────────────────●──── (production)
^ ^
dev ────●────●────●──────●────●────●──────────●──── (integration)
^ ^ ^ ^ ^
| | | | |
| | +- feature/ | +- feature/
| +- bugfix/ +- bugfix/
+- feature/
All feature and bugfix branches are created from dev. When dev is stable and QA-approved, it is merged into main for production deployment. Hotfixes are the sole exception: they branch from main and merge back to both main and dev.
| Branch Type | Prefix | Base Branch | Merges To | Example |
|---|---|---|---|---|
| Production | main |
-- | -- | main |
| Integration | dev |
-- | main |
dev |
| Feature | feature/ |
dev |
dev |
feature/TICKET-123-add-detector |
| Bug fix | bugfix/ |
dev |
dev |
bugfix/TICKET-456-fix-auth-loop |
| Hotfix | hotfix/ |
main |
main AND dev |
hotfix/fix-payment-crash |
feature/TICKET-123-short-descriptionWe use Conventional Commits. Every commit message must follow this structure:
type(scope): description
feat(humanizer): add anti-detection strength slider
fix(auth): resolve token refresh race condition
docs(api): update detector endpoint documentation
refactor(detector): extract score normalization logic
test(payments): add checkout flow integration test
chore(deps): update next.js to 16.0.10
perf(editor): optimize TipTap re-renders
| Type | Purpose |
|---|---|
feat |
A new feature or user-facing change |
fix |
A bug fix |
refactor |
Code restructuring with no behavior change |
docs |
Documentation only |
test |
Adding or updating tests |
chore |
Tooling, dependencies, config, CI changes |
perf |
Performance improvement |
| Scope | Area |
|---|---|
humanizer |
Humanizer feature |
detector |
AI detection feature |
auth |
Authentication and authorization |
payments |
Billing and checkout |
settings |
User/org settings |
documents |
Document management |
api |
API layer and endpoints |
i18n |
Internationalization |
deps |
Dependency updates |
editor |
TipTap editor |
infra |
Infrastructure and deployment |
The project uses Husky v8+ with lint-staged to enforce formatting before every commit.
git commit command via the .husky/pre-commit hooknpx lint-stagedThe single hook file at .husky/pre-commit contains:
npx lint-staged
| Problem | Solution |
|---|---|
| Hook does not fire on commit | Run npm run prepare to reinstall Husky hooks |
| "command not found: npx" | Ensure Node.js is on your PATH and dependencies are installed (npm install) |
| Hook fires but lint-staged skips files | Verify lint-staged config in package.json includes the correct file globs |
Note: Husky is installed via the
preparescript inpackage.json, which runs automatically afternpm install. If hooks stop working after a fresh clone,npm run preparewill re-initialize them.
Create a feature branch from dev
git checkout dev
git pull origin dev
git checkout -b feature/TICKET-123-add-detector
Make changes with atomic commits using the conventional commit format described above. Each commit should represent a single logical change.
Rebase on dev before pushing (or merge dev into your feature branch) to pick up recent changes and reduce merge conflicts:
git fetch origin
git rebase origin/dev
Push your branch:
git push -u origin feature/TICKET-123-add-detector
Open a PR targeting dev. Fill in the PR template completely:
Request review -- minimum 1 approval is required before merge.
Address review feedback by pushing new commits. Do not force-push on branches under review.
All CI checks must pass before merge:
Merge via squash merge (preferred) or merge commit. Squash merge keeps the dev history clean with one commit per PR.
Delete the remote branch after merge to keep the repository tidy.
feature branch
|
v
PR merged to dev
|
v
CI: lint + type-check + build
|
v
Deploy to staging
|
v
QA verification
|
v
PR from dev to main
|
v
Deploy to production
Code flows in one direction: feature branch --> dev --> staging --> main --> production. No changes skip the staging step except hotfixes, which follow an expedited path from main back through both main and dev.
main or dev. All changes go through pull requests.main, dev, or any branch with an open PR under review).dev into your feature branch before opening a PR to minimize conflicts.TICKET-123: Add detector endpoint).| Date | Author | Change |
|---|---|---|
| 2026-01-30 | Admin | Expanded with branch diagram, commit format details, pre-commit hook docs, full PR process, deployment pipeline, and rules |
| 2026-01-30 | Admin | Initial creation |
Next: Naming Conventions | Up: General