Git Workflow

Referenta uses dev as the integration branch and main as the production branch. Feature and fix work flows through short-lived branches cut from dev and opened as pull requests back into dev. Following the conventions on this page keeps Release Candidate branches stable and minimizes merge conflicts across the team.

The Role Of dev

dev is effectively a staging / Release Candidate branch. The next Release Candidate PR is a diff from dev to main that contains everything accumulated on dev since the last release, so anything merged into dev is implicitly committing to ship in the next RC.

Concretely:

• Anything merged into dev should be RC-ready. Treat the merge as a soft promise: the work is review-complete, doesn't depend on follow-up work that isn't also landing, and is safe to ship to production from the next release.
• Long-running work in progress stays on its own branch. A feature that is only half-finished, or a refactor that is waiting on a downstream API to stabilize, should not be merged into dev "to keep it in the loop." The moment incomplete work lands in dev, the next RC PR inherits it and is blocked until that work is either finished or reverted.
• A blocked dev blocks everyone. Other feature and fix branches that were genuinely ready to ship can't reach production while unfinished work sits in the RC. Avoid being the reason an RC stalls — other people's small, reviewed changes shouldn't have to wait on a long-standing in-progress branch you weren't ready to ship.

If you have a long-standing branch that needs to stay alive without merging into dev, keep it in sync with dev periodically (see When dev Moves Ahead Of Your Branch). Open the PR only when the work is genuinely complete and reviewed.

Standard Flow

git checkout dev
git pull origin dev

git checkout -b <type>/<short-description>

When dev Moves Ahead Of Your Branch

If dev advances while your branch is open — most visibly on Release Candidate PRs, where the diff against dev keeps growing — bring the latest dev into your branch:

git pull origin dev

Resolve any conflicts locally, commit the resolution, and push. The PR updates automatically. Avoid letting a stale branch sit far behind dev: the longer the gap, the more likely conflicts compound.

Direct Pushes To dev

Direct pushes to dev should only be used for very small and urgent fixes — a typo correction in a copy string, an immediate hotfix to an obviously-broken deploy. Everything else opens a PR.

The recommended default is always:

1. Update local dev.
2. Create a feature/fix branch from dev.
3. Open a PR back to dev.

If a change is too small to need a feature branch but you find yourself hesitating, that hesitation usually means it should go through a PR after all.

Be Careful With Git History

Git history on shared branches is a team contract. Rewriting it shifts other people's branches off their expected base, which is particularly painful on Release Candidate PRs that have already been reviewed against a specific commit.

Specifically:

• Never force-push to dev or main.
• Avoid amending commits that have already been pushed; create a follow-up commit instead.
• If you need to rewrite history on your own feature branch, do it before the first push.

Why This Workflow Matters

Following this flow keeps Release Candidate branches stable and minimizes merge conflicts across the team. The single most common source of cross-team pain — RC PRs spiraling into hard-to-resolve conflicts — is upstream feature branches getting created off stale dev and then needing forced re-bases late in the cycle. The cost of a git pull origin dev at the start is much lower than the cost of untangling that later.