Docs/Developer Guide/Git & Contribution Workflow

Git & Contribution Workflow

Basis: CONTRIBUTING.md, .github/PULL_REQUEST_TEMPLATE.md, .github/CODEOWNERS, .githooks/pre-push, scripts/dev/install-git-hooks.sh.
License: Apache-2.0; contributions accepted under the Developer Certificate of Origin.

1. The normal path (CONTRIBUTING.md)

Open an issue first for anything bigger than a bug fix.
Branch from main, keep the change focused, include tests.
Commit messages follow Conventional Commits, type(scope): summary, scope being the module or app — e.g. feat(knowledge): add web-crawl connector, fix(tenancy): ..., docs: ....
Sign off every commit (DCO): git commit -s -m "fix(tenancy): ...".
Open a pull request using the template and say exactly how you verified it.

The PR template asks for: what and why; how it was verified; and a checklist — commits signed off, new Flyway migration has a unique version across controlplane/ and tenant/ (bash scripts/ci/flyway-lint.sh), no secrets/tokens/personal data, docs or .env.example updated if behaviour or configuration changed. CODEOWNERS assigns default ownership and requires explicit maintainer review for migrations, core/crypto/, core/security/, .github/ and scripts/ci/. Security issues go through SECURITY.md, never a public issue.

2. Git hooks

make hooks                                 # once per clone; sets core.hooksPath = .githooks (or: bash scripts/dev/install-git-hooks.sh)
git config --unset core.hooksPath          # uninstall

Hooks live in the tracked .githooks/ directory, because .git/hooks is local and untracked. .githooks/pre-push reads the pushed refs and runs:

Push target	Checks run
`main`	The full static-gates suite: Flyway lint, bean/entity name guards, expired test-skip check, plan-price and file-size ratchets — plus the secret scan.
Any other branch touching `core/app/src/main/resources/db/migration`	Flyway lint, plus the secret scan.
Anything else	Secret scan only. It is skipped with a message when `gitleaks` is not installed.

Why the hook exists

A Flyway version collision that reaches main through a local merge fires no pull_request event, so CI never sees it, and it stops every core instance at boot. The hook is local enforcement that catches this before the push; it protects only clones where it is installed, so also require the CI OK and Static gates checks with branch protection. git push --no-verify bypasses it — never use it on a migration change.

3. Working with worktrees

Keep your main checkout clean. Use git worktree add for parallel branches instead of switching branches in a tree with uncommitted work.
Commit by pathspec when a tree holds unrelated edits: stage and commit explicit files (git commit -- <paths>) so unrelated work is not swept in.
git push has no pathspec. It publishes the whole branch. Before pushing, run git log --oneline origin/main..HEAD and read every line; to publish only up to a given commit use git push origin <sha>:<branch>.
Deploy from a clean worktree: git worktree add --detach "$SCRATCH/prod-deploy" <sha>, confirm git status --short is empty and the only .env* in web/ is .env.local.example, build, then git worktree remove --force.
Flyway numbers: when several branches add migrations in parallel, agree version ranges up front (e.g. in the tracking issue) — the namespace is shared across controlplane/ and tenant/.

4. Merge, CI and deploy — what "done" means

Pull requests run CI (summary check CI OK, which includes the static gates) and CodeQL; a maintainer reviews every PR and CodeQL must also be green (CONTRIBUTING.md). Reproduce locally with make gates, make test and make lint.
Releases: pushing a tag vX.Y.Z runs release.yml, which publishes signed multi-arch images and OCI Helm charts to GHCR, SPDX SBOMs, SLSA provenance and the vegaduta.tar.gz source tarball. No workflow deploys anywhere; you deploy with Compose or Helm. See Deployment Guide and CI/CD Pipelines.
Merged is not deployed. Record verification state exactly (compiled, unit-tested, staging, prod) in the PR.
Never run instance/revision reset|stop|delete or docker compose down on production or a shared staging stack.

Evidence & references

CONTRIBUTING.md — license/DCO, "Making a change", "Checks".
.github/PULL_REQUEST_TEMPLATE.md, .github/CODEOWNERS.
.githooks/pre-push, scripts/dev/install-git-hooks.sh (headers).
Makefile; .github/workflows/static-gates.yml, ci.yml, release.yml.