Pular para conteúdo

Conventions — Branches, Issues & Commits

Applies to: all Auraxis repositories (auraxis-api, auraxis-api-v2, auraxis-web, auraxis-app, auraxis-platform)

Status: Active since 2026-05-12

Issue Naming — Mandatory Prefixes

Every GitHub issue title must start with a prefix that identifies the target repository/domain:

Prefix Target Example
[API] auraxis-api-v2 (FastAPI v2) [API] JWT login — register, login, refresh
[BACKEND] auraxis-api (Flask v1) [BACKEND] Add GoalContribution model
[WEB] auraxis-web (Nuxt 4) [WEB] AI Insights dashboard card
[APP] auraxis-app (React Native) [APP] Spending history screen
[INFRA] Infrastructure / AWS [INFRA] Add v2 container to EC2
[DEVOPS] CI/CD, tooling, pipelines [DEVOPS] Configure GHCR image push
[PLATFORM] auraxis-platform (governance) [PLATFORM] Add auraxis-api-v2 submodule

Rule: No issue without a prefix. This enables filtering on the Projects board by repo/domain.

Branch Naming — Conventional Branching

Format: {type}/{issue-number}-{short-slug}

The issue number is mandatory in the branch name — no issue, no branch.

Type When to use
feat New feature or capability
fix Bug fix
refactor Code refactoring without behavior change
chore Dependencies, tooling, CI, config
docs Documentation only (ADRs, wiki, steering)
test Test-only changes
perf Performance improvement
security Security patch

Examples: 

feat/12-auth-jwt-login
fix/34-transaction-category-filter
chore/5-foundation-jwt-docker-setup
docs/7-adr-decisions-wiki
refactor/45-goal-repository-async
infra/89-add-v2-nginx-config

Commits — Conventional Commits (no exceptions)

Format: {type}({scope}): {imperative description}
Max 72 characters. Imperative mood ("add", "fix", "refactor" — not "added" or "adds").

Types: feat, fix, refactor, chore, docs, test, perf, security, style, ci

Examples: 

feat(auth): implement JWT login with refresh token rotation
fix(transactions): correct amount calculation for installment splits
refactor(goals): extract projection into GoalProjectionService
chore(deps): bump fastapi to 0.115.5
docs(adr): document JWT v1/v2 compatibility decision
test(auth): add edge cases for expired token rejection
ci(deploy): add health check step after container restart

Breaking change: append ! after type and explain in body: 

feat(auth)!: change token format to include jti and nbf

BREAKING CHANGE: clients must re-login after this deployment.
Existing sessions are invalidated.

Pull Requests

  • Every PR comes from a feature branch (see above)
  • PR body must contain Closes #N (or Fixes #N) referencing the issue
  • Without Closes #N, the board card won't auto-close on merge
  • Title follows the same conventional commits format as the squash commit
  • CI must be green before merge

GitHub Projects — Card Lifecycle

  1. Issue created → synced to board automatically via sync_repo_issues_to_project.py
  2. Work started → move card to In Progress
  3. PR opened → card stays In Progress
  4. PR merged → card auto-moves to Done via Closes #N
  5. If card doesn't auto-close → update manually via gh api graphql (see scripts)

Why These Conventions Matter

  • Prefix on issues: filters on Projects board instantly show work by domain
  • Issue number in branch: git log --oneline makes traceability obvious; GitHub auto-links branches to issues
  • Conventional commits: git log --oneline is readable; enables automatic changelog generation in the future; makes git bisect easier
  • Closes #N in PRs: closes the issue AND moves the board card in one step — no manual cleanup needed