diff --git a/.github/README.md b/.github/README.md index 187e5db25..58c25f273 100644 --- a/.github/README.md +++ b/.github/README.md @@ -193,8 +193,9 @@ This repository is the right place for any **organization-level** configuration: - **Changing contribution or security policies** — edit the corresponding file in `.github/` - **Updating dependency automation** — edit `renovate-config.json` and follow `../runbooks/dependency-management.md` -For a repository-specific Renovate exception, add a minimal `renovate.json` that -extends the organization preset and contains only the required override. +For a repository-specific Renovate exception, add a minimal +`.github/renovate.json` that extends the organization preset and contains only +the required override. ## Links diff --git a/renovate.json b/.github/renovate.json similarity index 100% rename from renovate.json rename to .github/renovate.json diff --git a/runbooks/branch-protection.md b/runbooks/branch-protection.md index 860879087..051058a92 100644 --- a/runbooks/branch-protection.md +++ b/runbooks/branch-protection.md @@ -13,14 +13,14 @@ still let `main` and `next` diverge, or lose the `next` branch outright, because the gaps are in _repository settings_ and _automation defaults_ that rulesets do not cover. Two incidents motivated this runbook: -1. `src` and `zsh-eza` both had `renovate.json` with no `baseBranches` +1. `src` and `zsh-eza` both had repository config with no `baseBranchPatterns` override. Renovate defaulted to the repository's default branch (`main`), opening routine dependency-update PRs that bypassed `next` entirely. Over time, enough of these (plus a few manually-merged feature branches) landed directly on `main` to diverge it from `next` by more than a dozen commits in `zsh-eza`'s case, with real merge conflicts to resolve before `next` could be promoted again. `dependency-management.md` already documents the - `baseBranches` override as an example — the actual gap was that nothing + `baseBranchPatterns` override as an example. The actual gap was that nothing audited whether a `next`-model repository had actually applied it. 2. Promoting `zsh-eza`'s `next` into `main` via a PR merge (`next` as the PR's head branch) triggered GitHub's "Automatically delete head branches" repo @@ -46,11 +46,9 @@ row is `next` → `main`. Skip repositories that are trunk-on-`main`. Keep this setting disabled as the required baseline for ordinary pull request merges. It is not a complete safeguard for GitHub's asynchronous stacked-merge path; see the caveat below. -- [ ] **`renovate.json` has `"baseBranches": ["next"]`** (or its newer - equivalent `"baseBranchPatterns": ["next"]` — Renovate accepts either - key for the same override; `zsh-lint` uses the newer name) if the +- [ ] **`.github/renovate.json` has `"baseBranchPatterns": ["next"]`** if the repository uses Renovate. See `dependency-management.md` for the full - config example. Check `.github/dependabot.yml`'s `target-branch` too — + config example. Check `.github/dependabot.yml`'s `target-branch` too: it is easy to fix Dependabot's target and assume Renovate inherited the same fix; they are independent configs. A repository with **no** Renovate config still needs `dependabot.yml`'s `target-branch` set for diff --git a/runbooks/dependency-management.md b/runbooks/dependency-management.md index abd263e04..9c70c8d87 100644 --- a/runbooks/dependency-management.md +++ b/runbooks/dependency-management.md @@ -50,14 +50,20 @@ also reference it explicitly: } ``` -Keep repository configuration small. Add `renovate.json` only for a real -exception, such as a non-default target branch: +Repository consumer configuration belongs at `.github/renovate.json`. +Renovate also recognizes `renovate.json` at the repository root, but searches +that location first and stops after the first match. Never keep both paths; a +migration must remove the root file in the same change that adds the preferred +file. + +Keep repository configuration small. Add `.github/renovate.json` only for a +real exception, such as a non-default target branch: ```json { "$schema": "https://docs.renovatebot.com/renovate-schema.json", "extends": ["local>z-shell/.github:renovate-config"], - "baseBranches": ["next"] + "baseBranchPatterns": ["next"] } ``` @@ -65,7 +71,7 @@ Custom managers and specialized package grouping also belong in the repository that needs them. For any repository whose `decisions/0008-branching-model.md` row is `next` → -`main`, this `baseBranches` override is not optional: without it Renovate +`main`, this `baseBranchPatterns` override is not optional: without it Renovate opens routine update PRs against `main` directly, bypassing `next`. This was found live (not theoretical) in two repositories — see `runbooks/branch-protection.md` for the full audit checklist. @@ -79,7 +85,8 @@ Do not remove Dependabot version updates until Renovate coverage is proven. the repository using the organization preset. 3. Confirm dependency graph, Dependabot alerts, and Dependabot security updates remain enabled in GitHub settings. -4. Add a minimal `renovate.json` only when the repository needs an override. +4. Add a minimal `.github/renovate.json` only when the repository needs an + override. 5. Delete `.github/dependabot.yml` to stop routine Dependabot version updates. 6. Confirm subsequent routine update pull requests come only from Renovate. @@ -94,7 +101,8 @@ Validate the shared preset or a repository override with Renovate itself: npx --yes --package renovate renovate-config-validator renovate-config.json ``` -For a repository override, replace the final path with `renovate.json`. +For a repository override, replace the final path with +`.github/renovate.json`. `jq empty` checks JSON syntax, but it does not prove that Renovate recognizes every option. diff --git a/runbooks/new-repository.md b/runbooks/new-repository.md index bf026f161..b45a619b9 100644 --- a/runbooks/new-repository.md +++ b/runbooks/new-repository.md @@ -137,10 +137,10 @@ Follow `runbooks/dependency-management.md`: 2. Confirm Renovate discovers `z-shell/.github/renovate-config.json`. 3. Enable the dependency graph, Dependabot alerts, and Dependabot security updates in GitHub settings. -4. Add `renovate.json` only for a repository-specific exception such as a - `next` target branch. If `decisions/0008-branching-model.md` assigns this - repository the `next` → `main` model, this exception is mandatory, not - optional — see `runbooks/branch-protection.md`. +4. Add `.github/renovate.json` only for a repository-specific exception such + as a `next` target branch. If `decisions/0008-branching-model.md` assigns + this repository the `next` → `main` model, this exception is mandatory, + not optional. See `runbooks/branch-protection.md`. 5. Do not add `.github/dependabot.yml` for routine version updates. ## Step 5a — Provision branch rulesets @@ -149,7 +149,7 @@ If this repository uses the `next` → `main` model (`decisions/0008-branching-model.md`), follow `runbooks/branch-protection.md` in full before opening the bootstrap pull request. Trunk-on-`main` repositories still need a `main` ruleset, but can skip the `next`-specific -items (the guard workflow, `renovate.json` override). +items (the guard workflow, `.github/renovate.json` override). ## Step 6 — Verify before publication diff --git a/scripts/test_validate_zsh_standard_policy.py b/scripts/test_validate_zsh_standard_policy.py index 818ccf77b..94ff12f20 100644 --- a/scripts/test_validate_zsh_standard_policy.py +++ b/scripts/test_validate_zsh_standard_policy.py @@ -1971,7 +1971,7 @@ def test_repair_2_consumer_parser_outputs_match_frozen_golden(self) -> None: self.assertEqual( digest, - "3860eff9c2566b91ec593c527f28046c615302a52e56ad0af9151405117f9953", + "581d64ea26a5bda6f3a8b139effe2abe31aeef947fc1a583f4740c4156dcd36d", ) def test_rejects_list_and_nested_container_rule_headings(self) -> None: