diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index b842e7fb..f7bcc977 100644 --- a/.github/MAINTENANCE.md +++ b/.github/MAINTENANCE.md @@ -237,7 +237,7 @@ We used this flow for PRs [#220](https://github.com/sickn33/antigravity-awesome- **Maintainer shortcut for batched PRs:** -- Use `npm run merge:batch -- --prs 450,449,446,451` to automate the ordered maintainer flow for multiple PRs. +- Use `npm run merge:batch -- --prs 450,449,446,451` to automate the ordered maintainer flow for multiple PRs. See [docs/maintainers/merge-batch.md](../docs/maintainers/merge-batch.md) for the short usage guide. - The script keeps the GitHub-only squash merge rule, handles fork-run approvals and stale PR metadata refresh, waits only on fresh required checks, retries `Base branch was modified`, and runs the mandatory post-merge `sync:contributors` follow-up on `main`. - It is intentionally not a conflict resolver. If a PR is conflicting, stop and follow the manual conflict playbook. diff --git a/docs/maintainers/merge-batch.md b/docs/maintainers/merge-batch.md new file mode 100644 index 00000000..371c5229 --- /dev/null +++ b/docs/maintainers/merge-batch.md @@ -0,0 +1,55 @@ +# Merge Batch + +`merge:batch` is the maintainer shortcut for merging multiple PRs in order while keeping the GitHub-only squash rule and the post-merge contributor sync. + +## Prerequisites + +- Start from a clean `main`. +- Make sure [`.github/MAINTENANCE.md`](/Users/nicco/Projects/antigravity-awesome-skills/.github/MAINTENANCE.md) is the governing policy. +- Have `gh` authenticated with maintainer permissions. +- Use this only for PRs that are already expected to merge; conflicting PRs still need the manual conflict playbook. + +## Basic Usage + +```bash +npm run merge:batch -- --prs 450,449,446,451 +``` + +Add `--poll-seconds ` if you want a slower or faster status loop while checks settle. + +## Happy Path + +`merge:batch` will: + +- refresh the PR body when the Quality Bar checklist is missing +- close and reopen the PR if stale metadata needs a fresh `pull_request` event +- approve fork runs waiting on `action_required` +- wait for the fresh required checks on the current head SHA +- merge with GitHub squash merge +- pull `main`, run `sync:contributors`, and push a README-only follow-up if needed + +## What It Automates + +- PR body normalization against the repository template +- stale PR metadata refresh +- required-check polling for the current PR head +- the post-merge contributor sync step +- the retry loop for `Base branch was modified` + +## What It Does Not Automate + +- conflict resolution on the PR branch +- manual judgment for risky skill changes +- README community-source audits when the source metadata is ambiguous +- fork-only edge cases that require contributor coordination outside GitHub permissions + +## When To Stop + +Stop and switch to the manual playbook when: + +- the PR is `CONFLICTING` +- `merge:batch` reports a check failure that needs source changes, not maintainer automation +- the PR needs a manual README credits decision +- fork approval or branch permissions are missing + +In those cases, follow [Merging Pull Requests](/Users/nicco/Projects/antigravity-awesome-skills/docs/maintainers/merging-prs.md) and the relevant sections in [MAINTENANCE.md](/Users/nicco/Projects/antigravity-awesome-skills/.github/MAINTENANCE.md). diff --git a/docs/maintainers/merging-prs.md b/docs/maintainers/merging-prs.md index 16a9e332..47b06a02 100644 --- a/docs/maintainers/merging-prs.md +++ b/docs/maintainers/merging-prs.md @@ -9,6 +9,7 @@ - Do **not** integrate a PR by squashing locally, pushing to `main`, and then closing the PR. That would show "Closed" and the contributor would not get proper credit. - Before merging, require the normal PR checks from [`.github/workflows/ci.yml`](../../.github/workflows/ci.yml) to be green. If the PR touches `SKILL.md`, also require the separate [`skill-review` workflow](../../.github/workflows/skill-review.yml) to pass. - For PRs that touch `SKILL.md` or risky guidance, require a real manual logic review in addition to the automated checks. Confirm the instructions, failure modes, and `risk:` label make sense before merging. +- For ordered multi-PR maintainer batches, use [Merge Batch](merge-batch.md) as the operational shortcut and keep this document as the policy reference. ## If the PR has merge conflicts @@ -77,5 +78,6 @@ Only if merging via GitHub is not possible (e.g. contributor unreachable and you ## References +- [Merge Batch](merge-batch.md) - [GitHub: Creating a commit with multiple authors](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors) - [GitHub: Merging a PR](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request) diff --git a/tools/scripts/tests/automation_workflows.test.js b/tools/scripts/tests/automation_workflows.test.js index 911c5360..99b5f543 100644 --- a/tools/scripts/tests/automation_workflows.test.js +++ b/tools/scripts/tests/automation_workflows.test.js @@ -133,11 +133,26 @@ assert.match( /- name: Audit npm dependencies[\s\S]*?run: npm audit --audit-level=high/, "CI should run npm audit at high severity", ); +assert.match( + ciWorkflow, + /source-validation:[\s\S]*?- uses: actions\/checkout@v4[\s\S]*?with:[\s\S]*?fetch-depth: 0/, + "source-validation should use an unshallowed checkout so base-branch diffs have a merge base", +); +assert.match( + ciWorkflow, + /source-validation:[\s\S]*?- name: Fetch base branch[\s\S]*?run: git fetch origin "\$\{\{ github\.base_ref \}\}"/, + "source-validation should fetch the PR base branch before changed-skill README credit checks", +); assert.match( ciWorkflow, /- name: Verify README source credits for changed skills[\s\S]*?run: npm run check:readme-credits -- --base "origin\/\$\{\{ github\.base_ref \}\}" --head HEAD/, "PR CI should verify README source credits for changed skills", ); +assert.match( + ciWorkflow, + /source-validation:[\s\S]*?- name: Fetch base branch[\s\S]*?- name: Install npm dependencies[\s\S]*?- name: Verify README source credits for changed skills/, + "source-validation should fetch the base branch before running the changed-skill README credit check", +); assert.match( ciWorkflow, /main-validation-and-sync:[\s\S]*?- name: Audit npm dependencies[\s\S]*?run: npm audit --audit-level=high/,