proofreading

Author: skarim

docs/src/content/docs/faq.md

@@ -5,11 +5,11 @@ description: Frequently asked questions about GitHub Stacked PRs.
 
 ## Creating Stacked PRs
 
-### What is a stacked PR? How is it different from a regular PR?
+### What is a Stacked PR? How is it different from a regular PR?
 
-A stacked PR is a pull request that is part of an ordered chain of PRs, where each PR targets the branch of the PR below it instead of targeting `main` directly. Each PR in the stack represents one focused layer of a larger change. Individually, each PR is still a regular pull request — it just has a different base branch and GitHub understands the relationship between the PRs in the stack.
+A Stacked PR is a pull request that is part of an ordered chain of PRs, where each PR targets the branch of the PR below it instead of targeting `main` directly. Each PR in the stack represents one focused layer of a larger change. Individually, each PR is still a regular pull request — it just has a different base branch, and GitHub understands the relationship between the PRs in the stack.
 
-### How do I create a stacked PR?
+### How do I create a Stacked PR?
 
 You can create a stack using the `gh stack` CLI:
 
@@ -27,13 +27,13 @@ You can also create stacks entirely from the GitHub UI — create the first PR n
 
 ### How do I add PRs to my stack?
 
-Use `gh stack add <branch-name>` to add a new branch on top of the current stack. When you run `gh stack submit`, a PR is created for each branch and they are linked together as a Stack on GitHub.
+Use `gh stack add <branch-name>` to add a new branch on top of the current stack. When you run `gh stack submit`, a PR is created for each branch, and they are linked together as a Stack on GitHub.
 
 You can also add PRs to an existing stack from the GitHub UI. See [Adding to an Existing Stack](/gh-stack/guides/ui/#adding-to-an-existing-stack) for details.
 
 ### How can I modify my stack?
 
-Reordering or inserting branches into the middle of a stack is not currently supported. To restructure a stack, use `gh stack unstack` to tear it down and then recreate it with `gh stack init --adopt`:
+Reordering or inserting branches into the middle of a stack is not currently supported. To restructure a stack, use `gh stack unstack` to tear it down and then re-create it with `gh stack init --adopt`:
 
 ```sh
 # 1. Remove the stack
@@ -54,26 +54,26 @@ gh stack init --adopt branch-2 branch-1 branch-3
 
 ### Can stacks be created across forks?
 
-No, stacked PRs currently require all branches to be in the same repository. Cross-fork stacks are not supported.
+No, Stacked PRs currently require all branches to be in the same repository. Cross-fork stacks are not supported.
 
 ## Checks, Rules & Requirements
 
-### How are branch protection rules evaluated for stacked PRs?
+### How are branch protection rules evaluated for Stacked PRs?
 
 Every PR in a stack is treated as if it is targeting the **base of the stack** (typically `main`), regardless of which branch it directly targets. This means:
 
 - **Required reviews** are evaluated as if the PR is targeting the stack base.
 - **Required status checks** are evaluated as if the PR is targeting the stack base.
-- **CODEOWNERS** are evaluated from the stack base — changes in codeowners on a PR at the bottom of the stack will not affect PRs above it in the stack.
+- **CODEOWNERS** are evaluated from the stack base — changes in `CODEOWNERS` on a PR at the bottom of the stack will not affect PRs above it in the stack.
 - **Code scanning workflows** are evaluated as if the PR is targeting the stack base.
 
-### How do GitHub Actions work with stacked PRs?
+### How do GitHub Actions work with Stacked PRs?
 
 GitHub Actions workflows trigger as if each PR in the stack is targeting the base of the stack (e.g., `main`). If you have a workflow configured to run on `pull_request` events targeting `main`, it will run for **every PR in the stack** — not just the bottom one.
 
 ### Do all previous PRs need to be passing checks before I can merge?
 
-Yes. In order to merge a PR in the stack, **all PRs below it** must also have passing checks and meet all merge requirements. For example, in a stack of `main <- PR1 <- PR2 <- PR3` and you want to merge PR #3, both PR #1 and PR #2 must have passing checks, required reviews, and satisfy all branch protection rules.
+Yes. In order to merge a PR in the stack, **all PRs below it** must also have passing checks and meet all merge requirements. For example, in a stack of `main <- PR1 <- PR2 <- PR3`, if you want to merge PR #3, both PR #1 and PR #2 must have passing checks, required reviews, and satisfy all branch protection rules.
 
 ### Is a linear history required?
 
@@ -86,13 +86,13 @@ If the stack is not linear (e.g., after changes were pushed to a lower branch),
 
 ## Merging Stacked PRs
 
-### What conditions need to be met for a stacked PR to be mergeable?
+### What conditions need to be met for a Stacked PR to be mergeable?
 
 Every PR in a stack must meet the same merge requirements as a PR targeting the stack base (e.g., `main`): required reviews, passing CI checks, CODEOWNER approvals, and a linear history. All PRs below it must also meet these requirements. See the [Checks, Rules & Requirements](#checks-rules--requirements) section above for details.
 
 ### How does merging a stack of PRs differ from merging a regular PR?
 
-Stacks must be merged **from the bottom up**. You can merge the bottom PR (and all non-merged PRs below it) in a single operation. After a PR is merged, the remaining stack is automatically rebased so the next PR targets `main` directly.
+Stacks must be merged **from the bottom up**. When you merge a PR, all non-merged PRs below it in the stack are also merged. After a PR is merged, the remaining stack is automatically rebased so the next PR targets `main` directly.
 
 ### What happens when you merge a PR in the middle of the stack?
 
@@ -114,23 +114,23 @@ With rebase merge, all of the commits from each PR in the stack are replayed ont
 
 PRs in a stack are merged sequentially, from the bottom up. When you initiate a merge, the bottom PR is merged first, and then the next PR above it, and so on. 
 
-There will not be a single push operation that adds all the commits from all the branches at once.
+Commits are not all landed in a single atomic operation — each PR is merged individually in sequence.
 
 ### Can I merge only part of a stack? What happens to the remaining unmerged PRs?
 
-Yes, partial stack merges are supported. After the merge, the lowest unmerged PR is updated to explicitly target the stack base (e.g. `main`). A cascading rebase is also automatically run to rebase the remaining unmerged branches.
+Yes, partial stack merges are supported. After the merge, the lowest unmerged PR is updated to explicitly target the stack base (e.g., `main`). A cascading rebase is also automatically run to rebase the remaining unmerged branches.
 
 ### What happens if you close a PR in the middle of the stack?
 
-Closing a PR in the middle of the stack will block all PRs above it from being mergeable. The stack relationship is preserved, so if you want to open a different PR or modify the stack, you will need to unstack and then recreate the stack.
+Closing a PR in the middle of the stack will block all PRs above it from being mergeable. The stack relationship is preserved, so if you want to open a different PR or modify the stack, you will need to unstack and then re-create the stack.
 
 ### What happens when there is an error merging a PR in the middle of a stack?
 
 If a merge fails (e.g., due to a failing check or merge conflict), the operation stops and no subsequent PRs are merged. You'll need to resolve the issue before continuing.
 
-### Does Stacked PRs support merge queue?
+### Do Stacked PRs support merge queue?
 
-Yes, stacked PRs fully support merging via merge queue. When you merge a stack through the merge queue:
+Yes, Stacked PRs fully support merging via merge queue. When you merge a stack through the merge queue:
 
 - **All PRs in the stack are added to the queue** in the correct order, ensuring a linear sequence.
 - **If a PR is removed or ejected from the merge queue**, all PRs above it in the stack are also ejected and removed from the queue.
@@ -154,7 +154,7 @@ No. Stacked PRs are built on standard git branches and regular pull requests. Yo
 
 ### Will this work with a different tool for stacking?
 
-Yes, you can continue to use your tool of choice (e.g. jj, Sapling, ghstack, git-town, etc.) to manage stacks locally and push up your branches to GitHub.
+Yes, you can continue to use your tool of choice (e.g., jj, Sapling, ghstack, git-town, etc.) to manage stacks locally and push up your branches to GitHub.
 
 Stacked PRs on GitHub are based on the standard pull request model — any tool that creates PRs with the correct base branches can work with them. The `gh stack` CLI is purpose-built for the GitHub experience, but other tools that manage branch chains should be compatible.
 

docs/src/content/docs/getting-started/quick-start.md

@@ -1,6 +1,6 @@
 ---
 title: Quick Start
-description: Install the gh stack CLI and create your first stacked PR in minutes.
+description: Install the gh stack CLI and create your first Stacked PR in minutes.
 ---
 
 ## Prerequisites

docs/src/content/docs/guides/stacked-prs.md

@@ -5,7 +5,7 @@ description: Practical guide for reviewing, merging, and managing stacked pull r
 
 This guide covers the practical day-to-day experience of working with Stacked PRs — how to review them, how merging works step by step, and how to keep things in sync from the CLI.
 
-For an introduction to what stacks are and how GitHub supports them natively, see the [Overview](/gh-stack/introduction/overview/). For a visual walkthrough of the UI, see [Using Stacks in the GitHub UI](/gh-stack/guides/ui/).
+For an introduction to what stacks are and how GitHub supports them natively, see the [Overview](/gh-stack/introduction/overview/). For a visual walkthrough of the UI, see [Stacked PRs in the GitHub UI](/gh-stack/guides/ui/).
 
 ## Reviewing Stacked PRs
 

docs/src/content/docs/guides/ui.md

@@ -1,6 +1,6 @@
 ---
 title: Stacked PRs in the GitHub UI
-description: A visual walkthrough of creating, navigating, merging, and managing stacked PRs directly in the GitHub pull request UI.
+description: A visual walkthrough of creating, navigating, merging, and managing Stacked PRs directly in the GitHub pull request UI.
 ---
 
 This guide walks through the key UI components and workflows for working with Stacked PRs on GitHub.
@@ -51,7 +51,7 @@ If a stack already exists and you want to add a new PR to it:
 
 ![Adding a new PR to an existing stack](../../../assets/screenshots/add-to-existing-stack.png)
 
-2. On the following page, the base branch is automatically set to the head of the top-most PR. Select the head branch for your new PR and click **Create pull request**.
+2. On the following page, the base branch is automatically set to the head of the topmost PR. Select the head branch for your new PR and click **Create pull request**.
 
 ![Selecting branch to add to stack](../../../assets/screenshots/selecting-branch-to-add.png)
 
@@ -79,7 +79,7 @@ Before a PR in the stack can be merged, the following conditions must be met:
 
 ## Unstacking
 
-If you want to reorder or reorganize the PRs in a stack, you must first dissolve the stack and then recreate it. You can unstack PRs from the UI.
+If you want to reorder or reorganize the PRs in a stack, you must first dissolve the stack and then re-create it. You can unstack PRs from the UI.
 
 ### Dissolving the Entire Stack
 

docs/src/content/docs/guides/workflows.md

@@ -135,7 +135,7 @@ This command:
 4. Pushes the updated branches
 5. Syncs PR state from GitHub
 
-If a conflict is detected during the rebase, all branches are restored to their original state and you're advised to run `gh stack rebase` to resolve conflicts interactively.
+If a conflict is detected during the rebase, all branches are restored to their original state, and you're advised to run `gh stack rebase` to resolve conflicts interactively.
 
 ## Structuring Your Stack
 

docs/src/content/docs/introduction/overview.md

@@ -91,7 +91,7 @@ While the PR UI provides the review and merge experience, the `gh stack` CLI han
 - **Tearing down stacks** — `gh stack unstack` removes a stack from GitHub and local tracking if you need to restructure it.
 - **Checking out a stack** — `gh stack checkout <pr-number>` pulls down a stack, with all its branches, from GitHub to your local machine.
 
-The CLI is not required to use Stacked PRs — the underlying git operations are standard. But it makes the workflow simpler, and you can create Stacked PRs from CLI instead of the UI.
+The CLI is not required to use Stacked PRs — the underlying git operations are standard. But it makes the workflow simpler, and you can create Stacked PRs from the CLI instead of the UI.
 
 ## Thinking About Stack Structure
 

docs/src/content/docs/reference/cli.md

@@ -138,7 +138,7 @@ Check out a stack from a pull request number or branch name.
 gh stack checkout [<pr-number> | <branch>]
 ```
 
-When a PR number is provided (e.g. `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you'll be prompted to resolve the conflict.
+When a PR number is provided (e.g., `123`), the command fetches the stack on GitHub, pulls the branches, and sets up the stack locally. If the stack already exists locally and matches, it switches to the branch. If the local and remote stacks have different compositions, you'll be prompted to resolve the conflict.
 
 When a branch name is provided, the command resolves it against locally tracked stacks only.
 
@@ -197,11 +197,11 @@ gh stack sync [flags]
 
 Performs a safe, non-interactive synchronization of the entire stack:
 
-1. **Fetch** — fetches the latest changes from `origin`
-2. **Fast-forward trunk** — fast-forwards the trunk branch to match the remote (skips if diverged)
-3. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state and you are advised to run `gh stack rebase` to resolve conflicts interactively
-4. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred)
-5. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR
+1. **Fetch** — fetches the latest changes from `origin`.
+2. **Fast-forward trunk** — fast-forwards the trunk branch to match the remote (skips if diverged).
+3. **Cascade rebase** — rebases all stack branches onto their updated parents (only if trunk moved). If a conflict is detected, all branches are restored to their original state, and you are advised to run `gh stack rebase` to resolve conflicts interactively.
+4. **Push** — pushes all branches (uses `--force-with-lease` if a rebase occurred).
+5. **Sync PRs** — syncs PR state from GitHub and reports the status of each PR.
 
 | Flag | Description |
 |------|-------------|