Promoting dev to main

Promoting dev to main

Core rule

Merge dev → main release PRs with a merge commit. Never squash or rebase these promotions.

Ordinary contribution PRs still target dev and may be squash-merged. The release promotion is the exception because main must retain dev in its ancestry. Squashing a promotion makes the next release re-present old commits and can create large false conflicts.

Workflow

1. Confirm the PR is exactly base=main, head=dev and no duplicate release PR is open.

2. Review main..dev, required CI, and deployment checks.

3. In GitHub, open the merge-method dropdown and choose Create a merge commit. With the CLI, use:

   gh pr merge <number> --repo Human-Agent-Society/CORAL --merge
   

4. Keep the long-lived dev branch. Do not delete or force-push it.

5. Fetch both branches and verify the released dev tip is an ancestor of main:

   git fetch origin dev main
   git merge-base --is-ancestor origin/dev origin/main
   

   Exit status 0 is required.

6. Confirm post-merge CI, release automation, deployments, and production smoke checks.

If GitHub reports conflicts

Do not force-rebase the shared dev branch. First inspect the topology and reproduce conflicts with git merge-tree.

If an earlier release was squash-merged, main may have the same tree as an earlier dev commit without sharing its ancestry. Verify tree equivalence before choosing a repair. Prefer merging main back into dev and pushing normally; use an ancestry-only ours merge only when exact tree equality proves main contains no unique content to preserve.

Red flags

• GitHub's primary button says Squash and merge.
• A command uses --squash, --rebase, or a force-push.
• The release workflow proposes deleting dev.
• Conflict resolution starts before checking commit topology and tree equality.

Stop when any red flag appears and return to the workflow above.

Quick reference

PR	Allowed merge method
Feature/fix/docs branch → dev	Repository default; usually squash
dev → main release promotion	Merge commit only