Repository navigation
Codify general repository settings + promotion-safety learnings - #261
Merged
Merged
Conversation
Settings config + rule: - Add repo-config/settings.json (the fleet-standard general settings) and extend repo-config/configure.sh to apply them (PATCH /repos) alongside the rulesets: wikis/projects off, rebase-merge off, merge+squash on, auto-merge on, update-branch on, delete-head OFF; plus the two state-dependent settings the script computes - has_discussions (public repos only) and default_branch (main, only when main exists). - Document the standard in repo-config/README.md "Repo Settings" and add a settings-drift check to AUDIT.md section 6. Promotion-safety learnings (AGENTS.md "Branching Model"): - Never delete develop during a develop->main promotion. The promotion PR's head IS develop, so `gh pr merge --delete-branch` (and the repo "auto-delete head branches" toggle, kept off for this reason) deletes develop. Includes the restore-from-head-SHA recovery. - Resolve spurious whole-file EOL conflicts (develop LF vs main CRLF) by taking develop on a throwaway branch off main - develop's linear-history + PR rulesets forbid resolving on develop directly. cspell: add idempotent/idempotently. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
Contributor
There was a problem hiding this comment.
Pull request overview
Codifies fleet-standard repository “general settings” as a committed config file applied by repo-config/configure.sh, and documents promotion-safety pitfalls (especially avoiding accidental develop deletion) plus the audit procedure for checking settings drift.
Changes:
- Add
repo-config/settings.jsonand extendrepo-config/configure.shto apply repo settings (with visibility/default-branch derived at runtime). - Document the settings policy and the
develop -> mainpromotion traps inrepo-config/README.mdandAGENTS.md. - Update the audit runbook to include a settings drift check; add
idempotent/idempotentlyto cspell.
Reviewed changes
Copilot reviewed 6 out of 6 changed files in this pull request and generated 3 comments.
Show a summary per file
| File | Description |
|---|---|
| repo-config/settings.json | Introduces a committed baseline for repo-level settings to apply consistently across the fleet. |
| repo-config/README.md | Documents the settings baseline and the “don’t delete develop” promotion safety constraint. |
| repo-config/configure.sh | Applies general repo settings in addition to rulesets, computing state-dependent fields. |
| cspell.json | Adds new allowed words and reformats the file. |
| AUDIT.md | Expands the audit procedure to include validating repo settings drift. |
| AGENTS.md | Records promotion-safety learnings directly in governance guidance. |
- repo-config/README.md: settings.json as a reference-style link (matches the
doc's convention), and PATCH /repos/{owner}/{repo} not PATCH /repos.
- repo-config/configure.sh: same endpoint precision in the header.
- AUDIT.md: the settings link now points at the file, not the repo-config/ dir.
Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
| - **`develop` is forward-only - no `main -> develop` back-merges.** The develop ruleset's squash-only setting physically blocks merge commits on develop. Historical back-merge commits visible in `git log` (`b9b0447`, `410ba56`, `ffb9e64`, `5ce95cf`, etc.) predate this rule and must not be repeated. | ||
| - **Executing a `develop -> main` promotion safely - two traps, both learned the hard way:** | ||
| - **Never delete `develop`.** A promotion PR's head *is* `develop`, so `gh pr merge --delete-branch` (and the repo's "Automatically delete head branches" toggle, which is why that toggle is [kept off](./repo-config/settings.json)) deletes `develop` itself. Merge a promotion with a plain `gh pr merge --merge`, no `--delete-branch`. If `develop` is ever lost this way, restore it to the merged PR's head SHA - the SHA is still reachable as the merge commit's second parent: `gh api -X POST "repos/<owner>/<repo>/git/refs" -f ref=refs/heads/develop -f sha="$(gh pr view <n> --json headRefOid --jq .headRefOid)"`. | ||
| - **Spurious EOL-only conflicts resolve by taking `develop`.** When develop declared workflow YAML as LF while main is still CRLF, `develop -> main` conflicts *whole-file* on those paths. develop's `required_linear_history` + PR rulesets forbid resolving on `develop` (no merge commit, no force-push), so resolve on a throwaway branch off `main`: `git checkout -b promote/develop-to-main origin/main && git merge origin/develop`, take develop's side for the EOL-conflicted files (`git checkout --theirs <file>`) **after confirming each is content-identical modulo EOL or that develop is a strict superset** (`diff <(git show :2:f|tr -d '\r') <(git show :3:f|tr -d '\r')`), then open that branch -> `main`. Verify no genuine main-only content is dropped (build/test where the repo supports it). |
ptr727
added a commit
that referenced
this pull request
Jul 9, 2026
…spec/registry updates (#267) Promotion of `develop` -> `main`, batching the merged PRs since the last promotion: - **#266** — merge-bot auto-merges every Dependabot tier (drop semver-major skip) + docs. - **#265** — WORKFLOW.md D1.4 correction (workflow changes are linted in CI). - **#264** — canonical WORKFLOW.md EOL note + repo-config JSON indent. - **#263** — spec: CODECOV_TOKEN for csharp/python repos + coverage policy. - **#262** — registry: mark MediaTools conformant. - **#261** — codify general repository settings + promotion-safety learnings. No code beyond template governance/config/spec; `spec/validate.py` green. 🤖 Generated with [Claude Code](https://claude.com/claude-code)
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
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.
Codifies the fleet-standard general repository settings as config + rule, and records two promotion-safety learnings from the develop→main sweep.
Settings as config + rule
repo-config/settings.json(new) — the fleet-standard general settings, applied idempotently byconfigure.sh(PATCH /repos) alongside the rulesets. The two state-dependent settings are computed by the script, not stored:has_discussions(public repos only) anddefault_branch(main, only when amainbranch exists — so a repo still on a rework branch isn't pointed at a missing default).repo-config/README.md"Repo Settings";AUDIT.md§6 gains a settings-drift check (renamed to "Validate Settings, Rulesets, and Secrets").Promotion-safety learnings (
AGENTS.md"Branching Model")developduring adevelop→mainpromotion. The promotion PR's head isdevelop, sogh pr merge --delete-branch(and the repo "auto-delete head branches" toggle — kept off for exactly this reason) deletesdevelop. Includes the restore-from-head-SHA recovery. (This bit me during the promotion sweep —developwas deleted on 3 repos and restored to their exact pre-merge SHAs; hence the codification.)main— develop'srequired_linear_history+ PR rulesets forbid resolving ondevelopdirectly.cspell.json: addidempotent/idempotently. All hub linters +spec/validate.pypass.🤖 Generated with Claude Code