Skip to content

Codify general repository settings + promotion-safety learnings - #261

Merged
ptr727 merged 2 commits into
developfrom
chore/codify-repo-settings
Jul 8, 2026
Merged

ptr727 merged 2 commits into
developfrom
chore/codify-repo-settings

Conversation

@ptr727

@ptr727 ptr727 commented Jul 8, 2026

Copy link
Copy Markdown
Owner

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 by configure.sh (PATCH /repos) alongside the rulesets. The two state-dependent settings are computed by the script, not stored: has_discussions (public repos only) and default_branch (main, only when a main branch exists — so a repo still on a rework branch isn't pointed at a missing default).
  • Standard: wikis/projects off, rebase-merge off, merge + squash on, auto-merge on, update-branch on, delete-head OFF, discussions public-only.
  • Documented in 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")

  • 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 exactly this reason) deletes develop. Includes the restore-from-head-SHA recovery. (This bit me during the promotion sweep — develop was deleted on 3 repos and restored to their exact pre-merge SHAs; hence the codification.)
  • Spurious whole-file EOL conflicts (develop declared workflow YAML LF while main is still CRLF) resolve by taking develop on a throwaway branch off main — develop's required_linear_history + PR rulesets forbid resolving on develop directly.

cspell.json: add idempotent/idempotently. All hub linters + spec/validate.py pass.

Deliberately not included: a change to the Copilot re-request mechanic. I hit a failure this session but traced it to my own wrong field name (botReviewerIds vs the runbook's botIds), so the runbook is likely correct and I left it untouched.

🤖 Generated with Claude Code

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>
Copilot AI review requested due to automatic review settings July 8, 2026 14:49

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.json and extend repo-config/configure.sh to apply repo settings (with visibility/default-branch derived at runtime).
  • Document the settings policy and the develop -> main promotion traps in repo-config/README.md and AGENTS.md.
  • Update the audit runbook to include a settings drift check; add idempotent/idempotently to 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.

Comment thread repo-config/README.md Resolved
Comment thread repo-config/configure.sh Resolved
Comment thread AUDIT.md Resolved
- 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>
Copilot AI review requested due to automatic review settings July 8, 2026 14:57
@ptr727
ptr727 merged commit fb427c1 into develop Jul 8, 2026
7 checks passed
@ptr727
ptr727 deleted the chore/codify-repo-settings branch July 8, 2026 14:58

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 1 comment.

Comment thread AGENTS.md
- **`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)
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants