You are viewing a plain text version of this content. The canonical link for it is here.
Posted to commits@magpie.apache.org by po...@apache.org on 2026/09/27 16:17:56 UTC

(magpie) branch main updated: docs: suggest the gh-stack extension when a change goes up as a series of dependent PRs (#1430)

This is an automated email from the ASF dual-hosted git repository.

potiuk pushed a commit to branch main
in repository https://gitbox.apache.org/repos/asf/magpie.git


The following commit(s) were added to refs/heads/main by this push:
     new 21db6fed docs: suggest the gh-stack extension when a change goes up as a series of dependent PRs (#1430)
21db6fed is described below

commit 21db6fedcd77afe33103e3e6c63bb46571dee51d
Author: Jarek Potiuk <ja...@potiuk.com>
AuthorDate: Sun Sep 27 18:17:50 2026 +0200

    docs: suggest the gh-stack extension when a change goes up as a series of dependent PRs (#1430)
    
    * docs: suggest the gh-stack extension when a change goes up as a series of dependent PRs
    
    GitHub's stacked PRs (the github/gh-stack extension) show a chain of
    dependent PRs as one stack. The agent conventions now say to check for
    the extension when a change is split into dependent PRs, suggest the
    user install it themselves (the secure setup denies extension installs
    from the agent), create each PR from its approved body with
    `gh pr create --base <previous branch> --web`, and join them with
    `gh stack link`. `gh stack submit --auto`, and letting `link` create PRs
    for bare branches, are ruled out because both post titles and bodies
    nobody approved.
    
    The same guidance goes into the AGENTS.md block setup writes for
    adopters (as a paragraph, so the setup skill's surface hash is
    unchanged), the fix-workflow template, and the prerequisites.
    
    Generated-by: Claude Opus 5
    
    * docs: suggest stacked PRs only with write access, and push their branches upstream
    
    A stacked PR's base is the previous PR's branch, and a PR can only
    target a branch in the repository it is opened against, so a stack
    only works when every branch lives in the upstream repository. The
    guidance now checks write access first
    (`gh api repos/<upstream> --jq .permissions.push`) and suggests the
    gh-stack extension only when it is true; the stack's branches are then
    pushed to the upstream repository, never to a fork, and the PRs are
    created and linked against it explicitly. Without write access the PRs
    go from the fork against the default branch, each with a
    "Depends on #N" line.
    
    Generated-by: Claude Opus 5
---
 AGENTS.md                                      | 16 ++++++++++++++++
 docs/quick-start/prerequisites.md              |  1 +
 plugins/magpie-setup/skills/setup/install.md   | 16 ++++++++++++++++
 plugins/magpie-setup/templates/fix-workflow.md | 14 ++++++++++++++
 4 files changed, 47 insertions(+)

diff --git a/AGENTS.md b/AGENTS.md
index c67a23d0..654eccc2 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -538,6 +538,22 @@ to a home-dir path and update the tool to read from there.
 - **Always open PRs with `gh pr create --web`** so the human reviewer can check the title,
   body, and the generative-AI disclosure in the browser before submission. Pre-fill `--title`
   and `--body-file` (including the Gen-AI disclosure block) so they only need to review, not edit.
+- **Stack a series of dependent PRs with GitHub's stacked PRs — only with write access to `<upstream>`.**
+  A stacked PR's base is the previous PR's branch, and a PR can only target a branch in the repository
+  it is opened against, so every branch of a stack must be pushed to `<upstream>` itself, never to a fork.
+  When one change is split into several PRs that each build on the previous one:
+  - Check write access with a plain `gh api repos/<upstream> --jq .permissions.push`.
+  - **`true`:** check for the [`github/gh-stack`](https://gh.io/stacks) extension with a plain `gh extension list`;
+    if it is missing, suggest the user install it themselves with `! gh extension install github/gh-stack` —
+    the secure setup denies extension installs from the agent, and installing one is the user's call.
+    Push every branch of the stack to `<upstream>` (its URL, not the fork's remote),
+    create each PR from its approved body file with `gh pr create --repo <upstream> --base <previous branch> --web`,
+    then join them bottom to top with `gh stack link --remote <upstream URL> <bottom-PR> … <top-PR>`.
+  - **Anything else:** do not suggest the extension. Push the branches to the fork and open each PR
+    against `<upstream>`'s default branch, one at a time or with a *"Depends on #N"* line naming the PR below it.
+  Never use `gh stack submit --auto`, or let `gh stack link` create a PR for a bare branch:
+  both post auto-generated titles and bodies nobody approved.
+  If the repository does not have stacks enabled, the base-chained PRs still work; say so and carry on.
 - **Pass long or multi-line message bodies to `gh` (and similar CLIs) through a file,
   never inline.**
   Write the text to a file in the session scratch directory or `$TMPDIR` first,
diff --git a/docs/quick-start/prerequisites.md b/docs/quick-start/prerequisites.md
index b5e685dd..f77f5757 100644
--- a/docs/quick-start/prerequisites.md
+++ b/docs/quick-start/prerequisites.md
@@ -215,6 +215,7 @@ JIRA), `contract:change-request` (GitHub PRs, JIRA patches, or dev@
   needs a fork of `<upstream>` on your GitHub account (it pushes a branch
   there, then opens the PR via `gh pr create --web`). Claude Code also
   ships a GitHub MCP; `gh` covers the rest and is what OpenCode uses.
+- **Optional: [`github/gh-stack`](https://gh.io/stacks), for maintainers with write access.** When a change goes up as a series of dependent PRs and you can push to the upstream repository, the agent suggests this `gh` extension, pushes the stack's branches to the upstream repository (a stacked PR's base must be a branch there, not in your fork), and links the PRs into a native GitHub stack with `gh stack link`. Without write access it opens the PRs from your fork instead, each noting th [...]
 - **JIRA / SVN-first projects.** No `gh` is required. The tracker is JIRA,
   review + merge run through `jira-patch` or `dev@` `[PATCH]` mail, and
   commits land via SVN — declare those backends in
diff --git a/plugins/magpie-setup/skills/setup/install.md b/plugins/magpie-setup/skills/setup/install.md
index 74b73fc2..d6fe55ca 100644
--- a/plugins/magpie-setup/skills/setup/install.md
+++ b/plugins/magpie-setup/skills/setup/install.md
@@ -1768,6 +1768,22 @@ framework before they hit a "skill not found" error:
    — never edit the snapshot directly. Framework changes go
    via PR to
    [`apache/magpie`](https://github.com/apache/magpie).
+
+   **Series of dependent PRs.** When a change is split into
+   PRs that build on each other and the contributor has write
+   access to this repository (`gh api repos/<upstream>
+   --jq .permissions.push` is `true`), stack them with GitHub's
+   stacked PRs: if `gh extension list` does not show
+   [`github/gh-stack`](https://gh.io/stacks), suggest the
+   contributor run `gh extension install github/gh-stack`
+   themselves; push every branch of the stack to this
+   repository, never a fork, since each PR's base is the
+   previous PR's branch; open each PR from its approved body
+   against that branch, in the browser, then
+   `gh stack link <bottom-PR> … <top-PR>`. Without write
+   access, open the PRs from the fork against the default
+   branch, each with a "Depends on #N" line. Never let
+   `gh stack` generate titles or bodies.
    ```
 
    **If the adopter installed the `pr-management-*` family**
diff --git a/plugins/magpie-setup/templates/fix-workflow.md b/plugins/magpie-setup/templates/fix-workflow.md
index 0b7557e3..39543a25 100644
--- a/plugins/magpie-setup/templates/fix-workflow.md
+++ b/plugins/magpie-setup/templates/fix-workflow.md
@@ -96,6 +96,20 @@ before submission. Pre-fill `--title` and `--body` (including the
 Gen-AI disclosure block) so the reviewer only needs to review, not
 edit.
 
+When a fix is split into several dependent PRs and the contributor
+has write access to the upstream repository
+(`gh api repos/<upstream> --jq .permissions.push` is `true`), stack
+them with GitHub's stacked PRs: suggest the contributor install the
+[`github/gh-stack`](https://gh.io/stacks) extension
+(`gh extension install github/gh-stack`) if `gh extension list`
+does not show it, push every branch of the stack to the upstream
+repository — never the fork, since each PR's base is the previous
+PR's branch — open each PR with `gh pr create --repo <upstream>
+--base <previous branch> --web`, then run `gh stack link <bottom-PR>
+… <top-PR>`. Without write access, open the PRs from the fork against
+the default branch, each with a "Depends on #N" line. Never let
+`gh stack` generate PR titles or bodies.
+
 ## Private-PR fallback
 
 The exceptional private-PR path (target branch `main` of the