docs: distinguish integration trunk from GitHub default branch#19
Merged
Conversation
The branch model table conflated two concepts under the single word "default": (1) the integration trunk that contributors branch from and PR against, and (2) GitHub's "default branch" repo setting that controls landing page, clone target, and PR-base UI suggestion. These are different concerns and the rules differ: - Integration trunk: develop, always. Doesn't change with release state. Where every change lands. - GitHub default branch setting: develop until first release, then main. So pre-release the landing page shows the integration state (the only meaningful state), and post-release it shows the shipped product to external visitors. Updates: 1. Rename develop's row in the branch model table from "Default branch" to "Integration trunk" and clarify its scope. 2. Add a new GitHub default branch setting subsection that names the distinction explicitly and states the rule. 3. Clarify the setup-repo description so it's clear develop-as- default is correct for new repos (no releases yet), with the flip happening at first release. 4. Add Step 5 to the release ceremony: ensure main is the GitHub default branch. Idempotent — only takes effect on the first release; no-op afterwards. 5. Update the release-ceremony-at-a-glance diagram to show the default flip at first release. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-Authored-By: amcheste <13696614+amcheste@users.noreply.github.com>
amcheste
approved these changes
May 12, 2026
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
2 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
The branch model docs conflated two distinct concepts under the single word "default":
develop.git clonetarget, and PR-base UI suggestion.These are different concerns and the rules differ:
develop. It doesn't change.developuntil first release, then flip tomainso external visitors see the shipped product on the landing page.What changes
mainis the GitHub default branch. Idempotent (only fires on first release; no-op after).Companion changes (separate PRs)
/publish-releaseskill update inmac-dev-setupto implement Step 5 in code.gh repo edit --default-branch mainon the 6 repos that have releases but currently still havedevelopas their GitHub default: assets, cam-brand, engineering-handbook, niche-hunter, overleaf-mcp, overleaf-mcp-site.The philosophy doc (
branching-strategy.md) doesn't need updates — its principle "main = latest release" is actually strengthened by this change (under the old model, landing on the repo showed develop, not main, so the principle was true but not the visitor's default experience).