From f47b2031701d5ccf6f8183a74f7aa59097f6eaa7 Mon Sep 17 00:00:00 2001 From: sck_0 Date: Sat, 7 Mar 2026 11:57:14 +0100 Subject: [PATCH] docs(MAINTENANCE): add reopen-and-merge flow and agent instruction for PRs - Document step-by-step flow to reopen closed PRs and merge via GitHub - Add agent instruction block: always merge via GitHub, never close after local integration; if closed, reopen and merge for contributor credit - Add shortcut link for Reopen & merge a closed PR --- .github/MAINTENANCE.md | 36 +++++++++++++++++++++++++++++++++++- 1 file changed, 35 insertions(+), 1 deletion(-) diff --git a/.github/MAINTENANCE.md b/.github/MAINTENANCE.md index d4c54197..599971a4 100644 --- a/.github/MAINTENANCE.md +++ b/.github/MAINTENANCE.md @@ -5,7 +5,7 @@ This guide details the exact procedures for maintaining `antigravity-awesome-skills`. It covers the **Quality Bar**, **Documentation Consistency**, and **Release Workflows**. -**Maintainer shortcuts:** [Merge a PR](#b-when-you-merge-a-pr-step-by-step) · [Post-merge & contributors](#c-post-merge-routine-must-do-before-a-release) · [Close issues](#when-to-close-an-issue) · [Create a release](#4-release-workflow) +**Maintainer shortcuts:** [Merge a PR](#b-when-you-merge-a-pr-step-by-step) · [Reopen & merge a closed PR](#if-a-pr-was-closed-after-local-integration-reopen-and-merge) · [Post-merge & contributors](#c-post-merge-routine-must-do-before-a-release) · [Close issues](#when-to-close-an-issue) · [Create a release](#4-release-workflow) --- @@ -84,6 +84,8 @@ Before ANY commit that adds/modifies skills, run the chain: ### B. When You Merge a PR (Step-by-Step) +> **Agent instruction (when analyzing or handling PRs):** Always merge accepted PRs via GitHub (**Squash and merge**). Never integrate locally and then close the PR. If a PR is closed but its changes were integrated locally, reopen it and follow [Reopen & merge](#if-a-pr-was-closed-after-local-integration-reopen-and-merge) so it ends up **Merged**. Contributors must get credit. + **Before merging:** 1. **CI is green** — Validation, reference checks, tests, and generated artifact steps passed (see [`.github/workflows/ci.yml`](workflows/ci.yml)). @@ -97,6 +99,38 @@ Before ANY commit that adds/modifies skills, run the chain: - **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). - **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):** + +If a PR was integrated via local squash and then **closed** (so it shows "Closed" instead of "Merged"), you can still give the contributor credit by reopening it and merging it on GitHub. The merge can be effectively "empty" (no new diff vs `main`); what matters is that the PR ends up **Merged**. + +1. **Reopen the PR** on GitHub (Reopen button on the closed PR page), or: `gh pr reopen `. +2. **Fetch the PR branch** (the branch lives on the contributor's fork): + ```bash + git fetch origin pull//head:pr--tmp + git checkout pr--tmp + ``` +3. **Merge `main` into it** and resolve conflicts: + ```bash + git merge origin/main -m "chore: merge main to resolve conflicts" + ``` + For conflicts in generated/registry files (`README.md`, `CATALOG.md`, `data/catalog.json`, etc.), keep **main's version**: + `git checkout --theirs README.md CATALOG.md data/catalog.json` (and any other conflicted files), then `git add` them. +4. **Commit the merge** (if not already done): + `git commit -m "chore: merge main to resolve conflicts" --no-edit` +5. **Push to the contributor's fork.** Add their fork as a remote if needed (replace `USER` and `BRANCH` with the PR head owner and branch from the PR page): + ```bash + git remote add -fork https://github.com//antigravity-awesome-skills.git + git push -fork pr--tmp: + ``` + This works if the contributor enabled **"Allow edits from maintainers"** (or you have push access). If push is denied, ask the contributor to merge `main` into their branch and push; then you use "Squash and merge" on GitHub. +6. **Merge the PR on GitHub:** + `gh pr merge --squash` + The PR will show as **Merged** and the contributor will get credit. +7. **Switch back to `main`:** + `git checkout main` + +We used this flow for PRs [#220](https://github.com/sickn33/antigravity-awesome-skills/pull/220), [#224](https://github.com/sickn33/antigravity-awesome-skills/pull/224), and [#225](https://github.com/sickn33/antigravity-awesome-skills/pull/225) after they had been integrated locally and closed. + **Right after merging:** 1. **If the PR had `Closes #N`** — The issue is closed automatically; no extra action.