diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index 599971a4..32e454bd 100644 --- a/.github/MAINTENANCE.md +++ b/.github/MAINTENANCE.md @@ -35,11 +35,13 @@ If you touch **any of these**: - Running `npm run chain` is **NOT optional**. - Running `npm run catalog` is **NOT optional**. -If CI fails with: +For contributor PRs, generated drift is now **informational** in CI because shared registry artifacts are auto-synced on `main` after merge. Contributors should still run the chain locally so the PR content is reviewable and maintainers can reproduce the generated output when needed. + +If `main` CI fails with: > `โŒ Detected uncommitted changes produced by registry/readme/catalog scripts.` -it means you **did not run or commit** the Validation Chain correctly. +it means the repository could not auto-sync generated artifacts cleanly and maintainer intervention is required. ### 3. ๐Ÿ“ EVIDENCE OF WORK @@ -79,7 +81,8 @@ Before ANY commit that adds/modifies skills, run the chain: git add README.md skills_index.json data/catalog.json data/bundles.json data/aliases.json CATALOG.md git commit -m "chore: sync generated files" ``` - > ๐Ÿ”ด **CRITICAL**: If you skip this, CI will fail with "Detected uncommitted changes". + > ๐Ÿ”ด **CRITICAL for direct `main` work**: If you skip this on maintainer work that lands directly on `main`, CI will fail with "Detected uncommitted changes". + > For contributor PRs, generated drift is allowed in CI and is auto-synced after merge. > See [`docs/maintainers/ci-drift-fix.md`](../docs/maintainers/ci-drift-fix.md) for details. ### B. When You Merge a PR (Step-by-Step) @@ -89,14 +92,14 @@ Before ANY commit that adds/modifies skills, run the chain: **Before merging:** 1. **CI is green** โ€” Validation, reference checks, tests, and generated artifact steps passed (see [`.github/workflows/ci.yml`](workflows/ci.yml)). -2. **No drift** โ€” PR does not introduce uncommitted generated-file changes; if the "Check for Uncommitted Drift" step failed, ask the author to run `npm run chain` and `npm run catalog` and commit the result. +2. **Generated drift understood** โ€” On pull requests, generator drift is informational only. Do not block a good PR solely because `README.md`, `CATALOG.md`, or catalog/index files would be regenerated. `main` auto-syncs those artifacts after merge. 3. **Quality Bar** โ€” PR description confirms the [Quality Bar Checklist](.github/PULL_REQUEST_TEMPLATE.md) (metadata, risk label, credits if applicable). 4. **Issue link** โ€” If the PR fixes an issue, the PR description should contain `Closes #N` or `Fixes #N` so GitHub auto-closes the issue on merge. **How you merge:** - **Always merge via GitHub** so the PR shows as **Merged** and the contributor gets credit. Use **"Squash and merge"**. Do **not** integrate locally and then close the PR โ€” that would show "Closed" and the contributor would not get proper attribution. -- **If the PR has merge conflicts:** Resolve them **on the PR branch** (you or the contributor: merge `main` into the PR branch, fix conflicts, run `npm run chain` and `npm run catalog` if needed, push). Then use **"Squash and merge"** on GitHub. Full steps: [docs/maintainers/merging-prs.md](../docs/maintainers/merging-prs.md). +- **If the PR has merge conflicts:** Resolve them **on the PR branch** (you or the contributor: merge `main` into the PR branch, fix conflicts, run `npm run chain` and `npm run catalog` if needed, push). For generated registry files, prefer keeping `main`'s side and regenerating rather than hand-editing conflicts. Then use **"Squash and merge"** on GitHub. Full steps: [docs/maintainers/merging-prs.md](../docs/maintainers/merging-prs.md). - **Rare exception:** Only if merging via GitHub is not possible, you may integrate locally and close the PR; in that case you **must** add a Co-authored-by line to the commit and explain in a comment. Prefer to avoid this so PRs are always **Merged**. **If a PR was closed after local integration (reopen and merge):** diff --git a/.github/workflows/ci.yml b/.github/workflows/ci.yml index 1a07ec3f..11b94648 100644 --- a/.github/workflows/ci.yml +++ b/.github/workflows/ci.yml @@ -5,7 +5,7 @@ permissions: on: push: - branches: ["main", "feat/*"] + branches: ["main"] pull_request: branches: ["main"] workflow_dispatch: @@ -94,11 +94,35 @@ jobs: git commit -m "chore: sync generated registry files [ci skip]" git push origin HEAD + - name: โ„น๏ธ Report generated drift (PRs only) + if: github.event_name == 'pull_request' + run: | + if git diff --quiet; then + echo "No generated drift detected after validation/build." + exit 0 + fi + + echo "::notice::Generated registry/readme drift detected on this PR." + echo "This is informational only on pull requests because main auto-syncs generated artifacts after merge." + echo "Files changed by generators:" + git diff --name-only + { + echo "## Generated Drift" + echo + echo "This PR changes source files that regenerate shared registry artifacts." + echo "The drift is allowed on pull requests and will be auto-synced on \`main\` after merge." + echo + echo "Changed generated files:" + git diff --name-only | sed 's/^/- `/; s/$/`/' + } >> "$GITHUB_STEP_SUMMARY" + - name: ๐Ÿšจ Check for Uncommitted Drift + if: github.event_name == 'push' && github.ref == 'refs/heads/main' run: | if ! git diff --quiet; then echo "โŒ Detected uncommitted changes produced by registry/readme/catalog scripts." echo + echo "Main must be self-healing after the auto-sync step." echo "To fix locally, run the FULL Validation Chain, then commit and push:" echo " npm run chain" echo " npm run catalog" diff --git a/CHANGELOG.md b/CHANGELOG.md index 55e9e9bd..5217ee59 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -13,6 +13,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - Refreshed `README.md` release copy, star milestone badge, and TOC heading alignment so the top-level docs match the current `7.6.0` repository state. - Aligned the evergreen English docs with the current `7.6.0` / `1,250+ skills` repository state and removed emoji from active H2 headers to keep anchors stable under the maintenance rules. +- Updated maintainer CI/merge docs and workflow policy so generated registry drift is informational on PRs and auto-synced on `main`, reducing merge friction across concurrent skill submissions. ## [7.6.0] - 2026-03-12 - "Maintenance Sweep" diff --git a/docs/maintainers/ci-drift-fix.md b/docs/maintainers/ci-drift-fix.md index c350a944..136344c8 100644 --- a/docs/maintainers/ci-drift-fix.md +++ b/docs/maintainers/ci-drift-fix.md @@ -11,7 +11,12 @@ **Cause**: Scripts like `tools/scripts/generate_index.py`, `tools/scripts/update_readme.py`, and `tools/scripts/build-catalog.js` modify `README.md`, `skills_index.json`, `data/catalog.json`, `data/bundles.json`, `data/aliases.json`, and `CATALOG.md`. The workflow expects these files to have no changes after the scripts run. Any differences mean the committed repo is out-of-sync with what the generation scripts produce. -**How to Fix (DO THIS EVERY TIME):** +## Pull Requests vs Main + +- **Pull requests**: generated drift is reported as an informational notice only. Shared files like `README.md`, `CATALOG.md`, and `data/catalog.json` can legitimately move as other PRs merge. Do not treat PR drift as a merge blocker by itself. +- **`main` pushes**: drift is still strict. `main` must end the workflow clean after the auto-sync step. + +## How to Fix on `main` 1. Run the **FULL Validation Chain** locally: @@ -34,5 +39,11 @@ Scripts like `tools/scripts/generate_index.py`, `tools/scripts/update_readme.py` git push ``` +## Maintainer guidance for PRs + +- Validate the source change. +- If merge conflicts touch generated registry files, keep `main`'s version for those files, rerun `npm run chain` and `npm run catalog`, and push the refreshed branch. +- Let `main` auto-sync the final generated artifact set after merge. + **Summary**: -Always commit and push all changes produced by the registry, README sync, and catalog scripts. This keeps CI passing by ensuring the repository and generated artifacts stay in sync with the canonical `tools/scripts/*` pipeline. +Use generator drift as a hard failure only on `main`. On PRs, it is expected maintenance noise around shared generated artifacts and should be handled with branch refreshes, not blanket rejection. diff --git a/docs/maintainers/merging-prs.md b/docs/maintainers/merging-prs.md index 19312095..7129b6f8 100644 --- a/docs/maintainers/merging-prs.md +++ b/docs/maintainers/merging-prs.md @@ -12,6 +12,12 @@ Resolve conflicts **on the PR branch** so the PR becomes mergeable, then use "Squash and merge" on GitHub. +### Generated files policy + +- Treat `README.md`, `CATALOG.md`, `skills_index.json`, and `data/*.json` as **derived artifacts**, not hand-edited source of truth. +- If those files conflict during a PR refresh, prefer **`main`'s side**, then rerun `npm run chain` and `npm run catalog`. +- Do not block a PR only because shared generated files would be regenerated differently after other merges. `main` auto-syncs the final state after merge. + ### Steps (maintainer resolves conflicts on the contributorโ€™s branch) 1. **Fetch the PR branch** @@ -20,7 +26,9 @@ Resolve conflicts **on the PR branch** so the PR becomes mergeable, then use "Sq `git checkout pr-` 3. **Merge `main` into it** `git merge origin/main` - Resolve any conflicts in the working tree (e.g. `README.md`, `CATALOG.md`, `data/*.json`, `skills_index.json`). Run `npm run chain` and `npm run catalog` if registry files were touched, then `git add` the updated generated files. + Resolve any conflicts in the working tree. For generated registry files (`README.md`, `CATALOG.md`, `data/*.json`, `skills_index.json`), prefer `main`'s version and regenerate: + `git checkout --theirs README.md CATALOG.md data/catalog.json skills_index.json` + Then run `npm run chain` and `npm run catalog`, and `git add` the refreshed generated files. 4. **Commit the merge** `git add .` then `git commit -m "chore: merge main to resolve conflicts"` (or leave the default merge message). 5. **Push to the same branch the PR is from** diff --git a/walkthrough.md b/walkthrough.md index d9ea2987..ad7b03e0 100644 --- a/walkthrough.md +++ b/walkthrough.md @@ -17,6 +17,8 @@ - Fixed `tools/scripts/update_readme.py` so normal `npm run readme` runs preserve the existing `registry-sync` star/timestamp values instead of rewriting them on every execution, which was causing non-deterministic PR drift failures in CI. - Updated `tools/scripts/sync_repo_metadata.py` to expose the same explicit `--refresh-volatile` behavior for live star/timestamp refreshes, keeping release/metadata refresh flows available without destabilizing contributor PR checks. +- Updated `.github/workflows/ci.yml` so generated registry drift is informational on pull requests but still strict on `main`, with auto-sync remaining the canonical path for shared artifacts after merge. +- Updated `.github/MAINTENANCE.md`, `docs/maintainers/ci-drift-fix.md`, and `docs/maintainers/merging-prs.md` to document the lower-friction merge flow: validate source changes on PRs, keep `main` for generated conflicts, and let `main` auto-sync the final artifact set. - Verified the fix with: - `python3 tools/scripts/update_readme.py --dry-run` - `python3 tools/scripts/sync_repo_metadata.py --dry-run`