ContributingGit Workflow

Git workflow

main is production. Every merge to main deploys. So every change ships through a feature branch and a reviewed PR.

Branch naming

Use a short prefix that matches the kind of change. The repo enforces Conventional Commit titles on PRs (see below), so picking the right branch prefix makes the PR title obvious.

PrefixUse forExample
feat/New user-visible behaviourfeat/segment-bulk-export
fix/Bug fixfix/survey-trigger-null-pointer
chore/Tooling, deps, configchore/bump-prisma-5.20
docs/HubHubThe Go service that owns background processing, integrations, and the admin API. Sibling to Core. or repo docs onlydocs/add-prerequisites-page
refactor/Code change with no behaviour changerefactor/extract-segment-resolver
test/Tests onlytest/segment-edge-cases

Keep the slug under ~40 chars. Reference an issue number if one exists: fix/1234-survey-trigger-null.

git checkout main
git pull origin main
git checkout -b feat/segment-bulk-export
  • Expected: Branch created from the latest main.
  • Verify: git status shows On branch feat/segment-bulk-export; git log -1 matches origin/main.
  • If “your branch is behind origin/main” later: rebase, don’t merge: git pull --rebase origin main.
  • search-hint: git rebase vs merge feature branch

Conventional Commits (enforced on PR titles)

The repo’s PR title check rejects anything that doesn’t match the Conventional Commits format. The check runs on the PR title, not individual commit messages — so you can squash freely, but the final title has to be clean.

Format:

<type>(<optional scope>): <short summary>

Examples that pass:

feat(segments): add bulk CSV export
fix(survey-triggers): handle null targetingId
chore(deps): bump prisma to 5.20
docs(hub): add prerequisites page
refactor(api): extract segment resolver

Examples that fail:

Update code                  ← no type
feature: bulk export         ← "feature" is not a valid type
Fix bug                      ← no type, no detail

Valid types: feat, fix, chore, docs, refactor, test, perf, style, build, ci.

PR checklist

The repo’s Azure DevOps PR template (hivecfm-core/.azuredevops/pull_request_template.md) is the authoritative checklist. Mirror it here so you can prep before opening:

Run the local checks

pnpm build
pnpm lint
pnpm test
  • Expected: All three exit 0.
  • Verify: No warnings printed by pnpm build (the template explicitly asks you to confirm zero warnings).
  • If pnpm build fails on a stale Prisma client: run pnpm --filter @hivecfm/database db:migrate:dev and rebuild.
  • search-hint: pnpm build prisma client out of date

Self-review your diff

git diff main...HEAD

Read the whole diff like a reviewer would. Look for:

  • Stray console.log calls (the PR template requires zero).
  • Commented-out code (delete it; git history is the archive).
  • Hardcoded credentials or paths.
  • New env vars not added to .env.example.

Pull latest main

git pull --rebase origin main
  • Expected: Clean rebase, no conflicts.
  • If conflicts: resolve them in your editor, then git add <files> and git rebase --continue. Do not force-merge by aborting.

Open the PR

git push -u origin feat/segment-bulk-export

Then create the PR — pick one:

  • Web UI: the git push output prints an Azure DevOps URL like https://dev.azure.com/istnetworksrnd/HiveCFM/_git/hivecfm-core/pullrequestcreate?sourceRef=... — click it.
  • az CLI: az repos pr create --repository hivecfm-core --source-branch feat/segment-bulk-export --target-branch main --title "feat(segments): add bulk CSV export" (requires az login + az extension add --name azure-devops once).

Then in the PR body:

  • Fill in “How should this be tested?” — at least two concrete steps.
  • Add a screenshot or Loom for any UI change.
  • Tick every box in the Required checklist.
  • Add reviewers from the team (Azure DevOps doesn’t auto-request like GitHub CODEOWNERS does).

Rules for main

⚠️

Never git push --force to main. The branch is protected; the push will be rejected anyway, but the rule exists because the deploy pipeline assumes monotonic history. Force-pushing your own feature branch is fine before review; never after a reviewer has commented.

  • main is auto-deployed. Don’t merge unfinished work, even behind a feature flag, unless you’ve tested the flag-off path locally.
  • Don’t delete release tags (v*).
  • Long-lived branches (>2 weeks) drift; either land them or close them.

Reading further

Done — what’s next

→ Start your first real task in the Week 1 onboarding checklist.

API Explorer