HanseNexus Docs
Mint Starter Kit

Development

Git Workflow

Branch naming, commit format, PR conventions, and worktree-based development

Branch Naming

All branches follow a type/description pattern:

PrefixUse CaseExample
feat/New featuresfeat/vocabulary-import
fix/Bug fixesfix/login-redirect-loop
docs/Documentation changesdocs/deployment-guide
chore/Maintenance, dependencieschore/update-playwright

Commit Format

Commits use the format type: description:

feat: add vocabulary import from CSV
fix: resolve login redirect loop on expired sessions
docs: update deployment guide with staging steps
refactor: extract shared calendar logic to package
chore: update Playwright to v1.48
test: add regression test for duplicate vocabulary sets

Types: feat, fix, docs, refactor, chore, test

Pull Request Conventions

  • Title: Imperative mood, under 72 characters (e.g., “Add vocabulary import from CSV”)
  • Body: Describe why the change is needed, not just what changed
  • Merge strategy: Squash merge always
  • Labels: Use deploy:preview to trigger preview deployments for lexilink

Review Policy

ScopeReview Required?
packages/Yes
k8s/Yes
.github/Yes
Root config filesYes
Single app-only changesSelf-merge OK

Protected Branches

  • master — No direct push. All changes via PR.
  • staging — No direct push. Merge from master or feature branches.

Worktree Workflow

Git worktrees keep production, staging, and feature work isolated in separate directories:

# Layout
hn-monorepo/                    # master (production)
hn-monorepo-staging/            # staging branch
hn-monorepo-feat-<name>/        # feature branches from master

Creating Worktrees

# Staging worktree
git worktree add ../hn-monorepo-staging staging

# Feature worktree
git worktree add ../hn-monorepo-feat-auth -b feat/auth

Cleanup After Merge

git worktree remove ../hn-monorepo-feat-auth

Rule: One worktree per context — never mix environments in the same working directory. This prevents accidentally running staging secrets against production code or vice versa.

CI Integration

All PRs automatically trigger the CI pipeline:

  • Lint: Biome check on changed TS/JS files
  • Typecheck: TypeScript typecheck on all apps
  • Test: Vitest unit tests on changed packages
  • Build: Next.js build for each changed app
  • E2E: Playwright tests for calnexus and lexilink

CI must pass before merge. New pushes to the same branch cancel in-progress CI runs.

HanseNexus 2026