Skip to content

docs: clarify "shared branch" definition in git operations policy #2306

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Michael Flanakin (flanakin) wants to merge 1 commit into
base: dev
Choose a base branch
from
+7 −5
Open

docs: clarify "shared branch" definition in git operations policy #2306

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions AGENTS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -170,10 +170,12 @@ The PowerShell-based build system:

This repository supports production infrastructure managing significant revenue. All git operations must be non-destructive and preserve full commit history.

**What counts as "shared":** `main`, `dev`, and `features/*` branches. A personal `{username}/{branch}` branch is not shared, regardless of review or comment activity on it.
Comment on lines 171 to +173

**Permitted operations:**

- `git add`, `git commit`, `git push` (standard push only)
- `git merge` (merge commits to integrate branches — the only permitted way to sync with `dev` or resolve conflicts)
- `git merge` (merge commits to integrate branches — the only permitted way to sync a shared branch with `dev` or resolve its conflicts; on a personal `{username}/{branch}` branch, rebase is also permitted, see below)
- `git checkout`, `git switch`, `git branch` (branch creation and switching)
- `git worktree add`, `git worktree remove`, `git worktree prune` (worktree lifecycle)
- `git fetch`, `git pull` (with merge, not rebase)
Expand All @@ -182,13 +184,13 @@ This repository supports production infrastructure managing significant revenue.

**Prohibited operations:**

- `git rebase` — rewrites commit history. Never permitted on shared branches. Not permitted as a conflict resolution strategy.
- `git push --force` / `git push --force-with-lease` — destructive remote update. Never permitted.
- `git rebase` — rewrites commit history. Never permitted on a shared branch (`main`, `dev`, `features/*`), including as a conflict resolution strategy on one. Permitted on a personal `{username}/{branch}` branch, including to sync with `dev` or resolve a conflict with it.
- `git push --force` / `git push --force-with-lease` — destructive remote update. Never permitted on a shared branch (`main`, `dev`, `features/*`). Permitted on a personal `{username}/{branch}` branch, e.g. after a rebase.
- `git reset --hard` to a state behind the remote (discarding pushed commits)
- `git filter-branch`, `git reflog`-based history manipulation
- Any operation that rewrites, reorders, squashes, or deletes commits that have been pushed to the remote
- Any operation that rewrites, reorders, squashes, or deletes commits that have been pushed to the remote of a shared branch (`main`, `dev`, `features/*`)

**Conflict resolution:** When a branch has merge conflicts with `dev`, the only permitted approach is `git merge origin/dev` into the feature branch. This creates a merge commit and preserves all history.
**Conflict resolution:** When a shared branch has merge conflicts with `dev`, the only permitted approach is `git merge origin/dev` into it, creating a merge commit that preserves all history. On a personal `{username}/{branch}` branch, either `git merge origin/dev` or `git rebase origin/dev` is permitted.

**Common conflict patterns in this repository:**

Expand Down