jj-stack 0.1.0__tar.gz → 0.1.2__tar.gz

{jj_stack-0.1.0 → jj_stack-0.1.2}/.github/workflows/ci.yml

@@ -18,7 +18,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
@@ -51,7 +51,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: ${{ matrix.python-version }}
 
@@ -78,7 +78,7 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 

{jj_stack-0.1.0 → jj_stack-0.1.2}/.github/workflows/codeql.yml

@@ -23,10 +23,10 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
 
       - name: Initialize CodeQL
-        uses: github/codeql-action/init@v4.37.3
+        uses: github/codeql-action/init@v4.37.7
         with:
           languages: python
           build-mode: none
 
       - name: Analyze
-        uses: github/codeql-action/analyze@v4.37.3
+        uses: github/codeql-action/analyze@v4.37.7

{jj_stack-0.1.0 → jj_stack-0.1.2}/.github/workflows/release.yml

@@ -5,6 +5,11 @@ on:
     tags:
       - "v*"
   workflow_dispatch:
+    inputs:
+      release_tag:
+        description: Existing tag to publish to production; leave empty for TestPyPI
+        required: false
+        type: string
 
 permissions:
   contents: read
@@ -26,22 +31,36 @@ jobs:
         uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
         with:
           fetch-depth: 0
+          ref: ${{ inputs.release_tag || github.ref }}
 
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
       - name: Verify tag matches package version
-        if: startsWith(github.ref, 'refs/tags/v')
+        if: github.event_name == 'push' || inputs.release_tag != ''
         env:
-          RELEASE_TAG: ${{ github.ref_name }}
-        run: test "$RELEASE_TAG" = "v$(uv version --short)"
+          RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
+        run: |
+          test "$RELEASE_TAG" = "v$(uv version --short)"
+          test "$(git rev-parse HEAD)" = "$(git rev-parse "refs/tags/$RELEASE_TAG^{commit}")"
 
       - name: Verify tagged commit is on main
-        if: startsWith(github.ref, 'refs/tags/v')
+        if: github.event_name == 'push' || inputs.release_tag != ''
         run: git merge-base --is-ancestor HEAD refs/remotes/origin/main
 
+      - name: Verify release notes
+        if: github.event_name == 'push' || inputs.release_tag != ''
+        env:
+          RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
+        run: |
+          release_notes="release-notes/$RELEASE_TAG.md"
+          if ! test -s "$release_notes"; then
+            echo "::error file=$release_notes::Add human-written release notes for $RELEASE_TAG"
+            exit 1
+          fi
+
       - name: Install jj
         run: echo "$(tools/install-jj-release.sh "$JJ_VERSION")" >> "$GITHUB_PATH"
 
@@ -52,7 +71,7 @@ jobs:
         run: uv build
 
       - name: Test built distributions
-        run: python tools/check_release_artifacts.py
+        run: uv run --no-project --python 3.14 python tools/check_release_artifacts.py
 
       - name: Upload distributions
         uses: actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a # v7.0.1
@@ -63,7 +82,7 @@ jobs:
           retention-days: 7
 
   publish-testpypi:
-    if: github.event_name == 'workflow_dispatch'
+    if: github.event_name == 'workflow_dispatch' && inputs.release_tag == ''
     needs: build
     runs-on: ubuntu-latest
     timeout-minutes: 10
@@ -75,7 +94,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
@@ -94,7 +113,9 @@ jobs:
           dist/*
 
   publish-pypi:
-    if: github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')
+    if: >-
+      (github.event_name == 'push' && startsWith(github.ref, 'refs/tags/v')) ||
+      (github.event_name == 'workflow_dispatch' && inputs.release_tag != '')
     needs: build
     runs-on: ubuntu-latest
     timeout-minutes: 10
@@ -106,7 +127,7 @@ jobs:
 
     steps:
       - name: Set up uv
-        uses: astral-sh/setup-uv@c771a70e6277c0a99b617c7a806ffedaca235ff9 # v9.0.0
+        uses: astral-sh/setup-uv@20cfd1bf945f4377ade1205e4dbc17946fc9a30d # v10.0.1
         with:
           python-version: "3.14"
 
@@ -131,6 +152,11 @@ jobs:
       contents: write
 
     steps:
+      - name: Check out release
+        uses: actions/checkout@3d3c42e5aac5ba805825da76410c181273ba90b1 # v7.0.1
+        with:
+          ref: ${{ inputs.release_tag || github.ref }}
+
       - name: Download distributions
         uses: actions/download-artifact@3e5f45b2cfb9172054b4087a40e8e0b5a5461e7c # v8.0.1
         with:
@@ -140,10 +166,24 @@ jobs:
       - name: Publish GitHub release
         env:
           GH_TOKEN: ${{ github.token }}
-          RELEASE_TAG: ${{ github.ref_name }}
+          RELEASE_TAG: ${{ inputs.release_tag || github.ref_name }}
         run: |
-          if ! gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
-            gh release create "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --verify-tag \
-              --generate-notes --title "$RELEASE_TAG"
+          release_notes="release-notes/$RELEASE_TAG.md"
+          if gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" >/dev/null 2>&1; then
+            expected_notes="$(cat "$release_notes")"
+            published_notes="$(
+              gh release view "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" \
+                --json body --jq .body
+            )"
+            if test "$published_notes" != "$expected_notes"; then
+              echo "::error file=$release_notes::Published notes do not match $release_notes"
+              exit 1
+            fi
+            for artifact in dist/*; do
+              gh release verify-asset "$RELEASE_TAG" "$artifact" \
+                --repo "$GITHUB_REPOSITORY"
+            done
+          else
+            gh release create "$RELEASE_TAG" dist/* --repo "$GITHUB_REPOSITORY" \
+              --verify-tag --notes-file "$release_notes" --title "$RELEASE_TAG"
           fi
-          gh release upload "$RELEASE_TAG" --repo "$GITHUB_REPOSITORY" --clobber dist/*

{jj_stack-0.1.0 → jj_stack-0.1.2}/AGENTS.md

@@ -1,8 +1,3 @@
-# Work in progress
-
-This project is under heavy development. Do not make any attempt to write backwards
-compatibility code, migration code, or the like.
-
 ## Complexity control
 
 - A replacement is incomplete until it deletes the mechanism it supersedes in the same change.
@@ -13,10 +8,9 @@ compatibility code, migration code, or the like.
   external mutation to the identity and version observed while planning when the platform
   supports a conditional write or lease. Re-observe only when an earlier mutation invalidates a
   precondition or when an observed trigger or platform contract requires it.
-- Apply the cumulative complexity budgets after every code slice. CI runs
-  `uv run tools/check_complexity.py`; run it locally when the pinned `tokei` is installed. A
-  budget increase is a design stop that requires explicit review, not routine maintenance of the
-  budget file.
+- Apply the cumulative complexity budgets after every code slice. Run `just complexity` locally
+  when the pinned `tokei` is installed; CI invokes the underlying checker. A budget increase is a
+  design stop that requires explicit review, not routine maintenance of the budget file.
 - If the same subsystem needs a third consecutive hardening change, stop patching it and
   re-derive the design from the core invariants.
 
@@ -25,8 +19,8 @@ compatibility code, migration code, or the like.
 - This is a `jj` repo. Do not use `git` to work on the repo itself.
 - Do not use git worktree-based agent isolation in this repo. For isolated parallel work, use
   `jj workspace` instead.
-- Run the CLI locally with `uv run jj-stack ...` instead of invoking the module or virtualenv
-  path directly.
+- Run the CLI locally with `just run ...` instead of invoking the module or virtualenv path
+  directly.
 - Hard-wrap code and markdown files at 98 columns unless a file uses a different convention.
 
 # Commit messages
@@ -38,7 +32,7 @@ compatibility code, migration code, or the like.
 - Hard-wrap commit message bodies at 72 columns.
 - The body should explain the motivation for the change, the intended behavior or design outcome,
   and any important scope or design constraints.
-- Do not use the body to narrate the code or to record routine validation such as `./check.py`.
+- Do not use the body to narrate the code or to record routine validation such as `just check`.
 - Prefer explaining why the commit exists and what rule or user-visible behavior it is enforcing.
 
 # Documentation
@@ -47,9 +41,10 @@ compatibility code, migration code, or the like.
   rules and the public/internal split. Built-in `--help` text is held to the same standard as
   the user docs: assume jj/git familiarity, avoid `jj-stack` internal design jargon.
 - The web version of the user docs normally lives in the sibling jj repository at
-  `$(jj root)/../website`. When user-facing docs change here, inspect and update the corresponding
-  web docs there too when needed. If the change here is committed, commit the corresponding
-  website update in that repository as well; preserve unrelated work in either working copy.
+  `$(jj root)/../website`. When user-facing docs change here, run `just website`, inspect the
+  corresponding website changes, and update them as needed. If the change here is committed,
+  commit the corresponding website update in that repository as well; preserve unrelated work in
+  either working copy.
 - Active internal docs use ordinary technical language too. Introduce a project-specific term
   only when it names a real type, field, or enduring rule, define it at first use, and prefer
   describing concrete inputs and effects.
@@ -76,13 +71,9 @@ compatibility code, migration code, or the like.
 
 # Testing
 
-- Run `./check.py` before finishing a code change. Docs-only edits under `docs/` do not require
-  a test run.
-- Run `./check.py` for the default local Ruff, type-check, and test pass before finishing a
-  code change.
-- For focused test runs, do not use plain `uv run pytest ...`; it can miss the repo's package
-  path in this project layout. First run `uv sync --locked`, then invoke pytest through the repo
-  virtualenv, for example `.venv/bin/python -m pytest tests/unit/test_jj_client.py`.
+- Run `just check` for the default local Ruff, type-check, and test pass before finishing a code
+  change. Docs-only edits under `docs/` do not require a test run.
+- Run focused tests with `just test`, for example `just test tests/unit/test_jj_client.py`.
 - Before adding, modifying, removing, or reviewing tests, fixtures, helpers, or property
   scenarios, read and follow
   [docs/internals/testing-philosophy.md](docs/internals/testing-philosophy.md). Add or retain

{jj_stack-0.1.0 → jj_stack-0.1.2}/PKG-INFO

@@ -1,9 +1,10 @@
 Metadata-Version: 2.5
 Name: jj-stack
-Version: 0.1.0
+Version: 0.1.2
 Summary: Stacked GitHub pull requests for Jujutsu
 Project-URL: Homepage, https://www.serpentine.com/software/jj-stack/
 Project-URL: Documentation, https://www.serpentine.com/software/jj-stack/
+Project-URL: Changelog, https://github.com/bos/jj-stack/releases
 Project-URL: Repository, https://github.com/bos/jj-stack
 Project-URL: Issues, https://github.com/bos/jj-stack/issues
 License-Expression: Apache-2.0
@@ -20,6 +21,7 @@ Classifier: Topic :: Software Development :: Version Control
 Classifier: Topic :: Software Development :: Version Control :: Git
 Requires-Python: >=3.14
 Requires-Dist: httpxyz<0.32,>=0.31.0
+Requires-Dist: markdown-it-py<5,>=4.0.0
 Requires-Dist: pydantic<3,>=2.13.3
 Requires-Dist: rich<16,>=15.0.0
 Description-Content-Type: text/markdown
@@ -35,31 +37,51 @@ matching PRs.
 ### Requirements
 
 - Python 3.14 or newer
-- `uv`
 - `jj` 0.44.0 or newer
 - GitHub authentication
 
 ### Install
 
-Install `jj-stack` from PyPI:
+Install `jj-stack` from PyPI with `uv` in an isolated tool environment (recommended):
 
 ```bash
 uv tool install jj-stack
 ```
 
-To upgrade, rerun that command with `--force`. If the command is not on your shell `PATH`, run
-`uv tool update-shell`.
+`pipx` provides another isolated installation:
 
-For tab completion, add the output of `jj-stack completion` to your shell startup file:
+```bash
+pipx install jj-stack
+```
+
+You can also use `pip` inside an activated virtual environment:
 
 ```bash
-eval "$(jj-stack completion zsh)"
+python -m pip install jj-stack
 ```
 
-`bash` and `fish` work the same way.
+To upgrade an installation made with `uv`, rerun its command with `--force`. If the command is
+not on your shell `PATH`, run `uv tool update-shell`.
+
+### Invoke it as `jj stack`
+
+Add a command alias to your user configuration with `jj config edit --user`:
+
+```toml
+[aliases]
+stack = ["util", "exec", "--", "jj-stack"]
+```
 
-To invoke it as `jj stack` and complete that alias too, see
-[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/).
+For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
+your shell startup file:
+
+```bash
+eval "$(jj-stack completion zsh --jj-alias stack)"
+```
+
+`bash` and `fish` work the same way. See
+[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/) for more
+setup options.
 
 ### Submit your first stack
 
@@ -126,7 +148,7 @@ merge queues, cleanup, and working with multiple stacks.
 - [Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/)
 - [Writing PR descriptions](https://www.serpentine.com/software/jj-stack/reference/descriptions/)
 - [Troubleshooting](https://www.serpentine.com/software/jj-stack/troubleshooting/)
-- [`jj-stack` and `gh stack`](https://www.serpentine.com/software/jj-stack/gh-stack/)
+- [Tool comparison](https://www.serpentine.com/software/jj-stack/tool-comparison/)
 - [JSON output](https://www.serpentine.com/software/jj-stack/reference/json-output/)
 - [Automation and exit codes](https://www.serpentine.com/software/jj-stack/reference/automation/)
 
@@ -138,6 +160,12 @@ jj-stack <command> --help
 jj-stack help --all
 ```
 
+## Development
+
+Contributor workflows live in the [`justfile`](justfile). With `uv`, `jj`, and `just` installed,
+run `just` to list the setup, formatting, focused test, verification, documentation, and release
+recipes.
+
 ## Coding agent integration
 
 Install the bundled skill to teach coding agents to work with local `jj` stacks and refresh their

{jj_stack-0.1.0 → jj_stack-0.1.2}/README.md

@@ -9,31 +9,51 @@ matching PRs.
 ### Requirements
 
 - Python 3.14 or newer
-- `uv`
 - `jj` 0.44.0 or newer
 - GitHub authentication
 
 ### Install
 
-Install `jj-stack` from PyPI:
+Install `jj-stack` from PyPI with `uv` in an isolated tool environment (recommended):
 
 ```bash
 uv tool install jj-stack
 ```
 
-To upgrade, rerun that command with `--force`. If the command is not on your shell `PATH`, run
-`uv tool update-shell`.
+`pipx` provides another isolated installation:
 
-For tab completion, add the output of `jj-stack completion` to your shell startup file:
+```bash
+pipx install jj-stack
+```
+
+You can also use `pip` inside an activated virtual environment:
 
 ```bash
-eval "$(jj-stack completion zsh)"
+python -m pip install jj-stack
 ```
 
-`bash` and `fish` work the same way.
+To upgrade an installation made with `uv`, rerun its command with `--force`. If the command is
+not on your shell `PATH`, run `uv tool update-shell`.
+
+### Invoke it as `jj stack`
+
+Add a command alias to your user configuration with `jj config edit --user`:
+
+```toml
+[aliases]
+stack = ["util", "exec", "--", "jj-stack"]
+```
 
-To invoke it as `jj stack` and complete that alias too, see
-[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/).
+For tab completion of both `jj-stack` and `jj stack`, add the output of `jj-stack completion` to
+your shell startup file:
+
+```bash
+eval "$(jj-stack completion zsh --jj-alias stack)"
+```
+
+`bash` and `fish` work the same way. See
+[Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/) for more
+setup options.
 
 ### Submit your first stack
 
@@ -100,7 +120,7 @@ merge queues, cleanup, and working with multiple stacks.
 - [Configuration](https://www.serpentine.com/software/jj-stack/reference/configuration/)
 - [Writing PR descriptions](https://www.serpentine.com/software/jj-stack/reference/descriptions/)
 - [Troubleshooting](https://www.serpentine.com/software/jj-stack/troubleshooting/)
-- [`jj-stack` and `gh stack`](https://www.serpentine.com/software/jj-stack/gh-stack/)
+- [Tool comparison](https://www.serpentine.com/software/jj-stack/tool-comparison/)
 - [JSON output](https://www.serpentine.com/software/jj-stack/reference/json-output/)
 - [Automation and exit codes](https://www.serpentine.com/software/jj-stack/reference/automation/)
 
@@ -112,6 +132,12 @@ jj-stack <command> --help
 jj-stack help --all
 ```
 
+## Development
+
+Contributor workflows live in the [`justfile`](justfile). With `uv`, `jj`, and `just` installed,
+run `just` to list the setup, formatting, focused test, verification, documentation, and release
+recipes.
+
 ## Coding agent integration
 
 Install the bundled skill to teach coding agents to work with local `jj` stacks and refresh their

{jj_stack-0.1.0 → jj_stack-0.1.2}/check.py

@@ -18,6 +18,7 @@ VENV_PYTHON = (
     REPO_ROOT / ".venv" / (Path("Scripts/python.exe") if os.name == "nt" else Path("bin/python"))
 )
 PytestJobs = int | Literal["auto"]
+_PYREFLY_TARGETS = ("src", "tests", "tools", "check.py")
 _FRAGILE_TEST_OUTPUT_PATTERNS: tuple[tuple[str, re.Pattern[str]], ...] = (
     (
         "use output assertion helpers instead of exact captured output equality",
@@ -77,10 +78,17 @@ def _build_checks(
     return (
         ("ruff", ("-m", "ruff", "check")),
         ("ruff-format", ("-m", "ruff", "format", "--check")),
-        ("pyrefly", ("-m", "pyrefly", "check")),
+        ("pyrefly", ("-m", "pyrefly", "check", *_PYREFLY_TARGETS)),
         (
             "pyrefly-windows",
-            ("-m", "pyrefly", "check", "--python-platform", "win32"),
+            (
+                "-m",
+                "pyrefly",
+                "check",
+                "--python-platform",
+                "win32",
+                *_PYREFLY_TARGETS,
+            ),
         ),
         ("pytest", pytest_command),
     )

{jj_stack-0.1.0 → jj_stack-0.1.2}/complexity-budget.toml

@@ -49,6 +49,7 @@ governed = [
   "src/jj_stack/commands/sync.py",
   "src/jj_stack/commands/sync_apply.py",
   "src/jj_stack/models/tracking.py",
+  "src/jj_stack/state/migrations.py",
   "src/jj_stack/state/store.py",
   "src/jj_stack/stack/trunk_evidence.py",
   "src/jj_stack/stack/convergence.py",

{jj_stack-0.1.0 → jj_stack-0.1.2}/docs/README.md

@@ -23,12 +23,13 @@ web navigation and presentation.
 ## Reference and troubleshooting
 
 - [Command reference](reference/commands.md)
+- [Bookmarks and stack selection](reference/bookmarks-and-selection.md)
 - [Configuration](reference/configuration.md)
 - [Pull request descriptions](reference/descriptions.md)
 - [Automation and agents](reference/automation.md)
 - [JSON output](reference/json-output.md)
 - [Troubleshooting](troubleshooting.md)
-- [`jj-stack` and `gh stack`](gh-stack.md)
+- [Compare `jj-stack` with other tools](tool-comparison.md)
 
 The built-in help is the exact flag and alias reference:
 

{jj_stack-0.1.0 → jj_stack-0.1.2}/docs/guides/continue-a-stack.md

@@ -30,9 +30,8 @@ Choose any pull request in your stack:
 jj-stack checkout --pull-request <pr>
 ```
 
-`checkout` follows the selected pull request down to the bottom of its stack, fetches those
-commits, records which local change belongs to each pull request, and runs `jj edit` on the
-selected pull request's change.
+`checkout` follows that pull request down to the bottom of its stack, fetches those commits,
+records which local change belongs to each pull request, and runs `jj edit` on its change.
 
 To start a new change on top instead of editing that change directly, run:
 
@@ -54,4 +53,5 @@ jj-stack submit <head-change-id>
 ```
 
 `relink` is a repair command for this specific mismatch. It verifies that your pull request's
-branch belongs to your selected change; it cannot attach an unrelated pull request to new work.
+branch belongs to the local change you chose; it cannot attach an unrelated pull request to new
+work.

{jj_stack-0.1.0 → jj_stack-0.1.2}/docs/guides/merge-and-sync.md

@@ -52,9 +52,9 @@ After GitHub merges some or all of your pull requests, `sync` fetches trunk, rem
 changes from your local history if needed, rebases your remaining changes, updates your remaining
 pull requests, and removes your PR branches when they are no longer needed.
 
-If no selected pull request has merged and GitHub has not rebased the stack, `sync` reports that
-there are no merged changes and leaves the pull requests unchanged. Run `submit` explicitly when
-you want to publish local changes.
+If none of the pull requests in your stack has merged and GitHub has not rebased the stack,
+`sync` reports that there are no merged changes and leaves the pull requests unchanged. Run
+`submit` explicitly when you want to publish local changes.
 
 What does “removes the merged changes from your local history” mean? If GitHub uses a merge
 commit or rebase merge for your pull requests, it preserves their `jj` change IDs, and
@@ -69,16 +69,16 @@ not need to run another cleanup command.
 
 ### Merge queues
 
-When `merge` uses a merge queue, it returns successfully once GitHub accepts your selected pull
-requests into the queue. This does not mean trunk has changed. Wait until GitHub reports that
-your stack has merged. Then run `sync` with the head of your stack:
+When `merge` uses a merge queue, it returns successfully once GitHub accepts the pull requests
+you asked it to merge. This does not mean trunk has changed. Wait until GitHub reports that your
+stack has merged. Then run `sync` with the head of your stack:
 
 ```console
 jj-stack sync <head-change-id>
 ```
 
-If you run either command while one of your selected pull requests is queued, `submit` and `sync`
-leave your stack unchanged.
+If you run either command while one of those pull requests is queued, `submit` and `sync` leave
+your stack unchanged.
 
 ### Merges outside jj-stack
 
@@ -113,9 +113,9 @@ to it. It also removes branches, comments, and saved pull-request links for merg
 local changes are gone. If one stack cannot be updated, jj-stack explains why and continues with
 independent stacks.
 
-Like selected `sync`, `sync --all` does not rebase a stack merely because trunk advanced. A
-selected `sync` also recognizes a completed native GitHub stack rebase because GitHub moved every
-PR branch and the rewritten contents can be verified.
+`sync --all` and `sync <head-change-id>` do not rebase a stack merely because trunk advanced.
+`sync <head-change-id>` also recognizes a completed native GitHub stack rebase because GitHub
+moved every PR branch and the rewritten contents can be verified.
 
 ## If `merge` fails after GitHub merges your pull requests
 

{jj_stack-0.1.0 → jj_stack-0.1.2}/docs/guides/review-a-stack.md

@@ -11,11 +11,17 @@ locally; reviewers work with native stacked pull requests on GitHub.
 
 ## Read the stack map
 
-GitHub shows the ordered stack and each pull request's position. Start at the bottom, which is
-closest to the final base branch, and move upward. Each pull request's **Files changed** view is
-the diff for that layer, not the cumulative diff from the final base. Review and approve each
+GitHub shows the ordered stack and each pull request's position. Start at the bottom, where the
+stack branches from its base branch, and move upward. Each pull request's **Files changed** view
+is the diff for that layer, not the cumulative diff from the base branch. Review and approve each
 layer independently, while reading a higher layer with its dependencies in mind.
 
+From a checkout that tracks the stack, you can print the same order before opening GitHub:
+
+```console
+jj-stack view --pull-request <pr>
+```
+
 ## Review and merge in order
 
 Comments, requested changes, approvals, CODEOWNERS, and required checks remain per pull request.

{jj_stack-0.1.0 → jj_stack-0.1.2}/docs/guides/submit-and-update.md

@@ -78,6 +78,12 @@ previously approved or asked for changes (i.e. revoking the approved state of yo
 jj-stack submit --re-request
 ```
 
+## PR history
+
+To make it easier for a reader to understand how a pull request has changed over time, when you
+run `submit` to update a PR that you have submitted before, `jj-stack` will keep a comment up to
+date on the PR that shows its most recent versions, with a link to the diff for each update.
+
 ## What the `submit` command changes
 
 | Surface | Effect |
@@ -86,6 +92,7 @@ jj-stack submit --re-request
 | PR branches | Created or updated |
 | Pull requests | Created or updated |
 | Pull request order | Updated to match the local change order |
+| Pull request comments | Revision history maintained |
 | Other local stacks | Not changed |
 
 With `jj`, you can easily move your changes between existing stacks. However, GitHub allows each