From 9540aba1644de959e883ca67292944b1ff4981ba Mon Sep 17 00:00:00 2001 From: Mattias Granlund Date: Tue, 26 Nov 2024 08:54:29 +0000 Subject: [PATCH] Fix some grammar in stacked branches page --- content/docs/features/stacked-branches.mdx | 42 +++++++++++----------- 1 file changed, 21 insertions(+), 21 deletions(-) diff --git a/content/docs/features/stacked-branches.mdx b/content/docs/features/stacked-branches.mdx index 2094ddd..bcb6b62 100644 --- a/content/docs/features/stacked-branches.mdx +++ b/content/docs/features/stacked-branches.mdx @@ -4,7 +4,7 @@ title: Stacked Branches import ImageSection from "@/components/ImageSection" -Create a queue of dependent branches to be reviewed and merged in order. +Create a stack of dependent branches to be reviewed and merged in order. ## Overview @@ -18,7 +18,7 @@ This is useful when you have multiple changesets that depend on each other but i ## Use cases -Using stacked branches (Pull Requests) can be helpful for shipping smaller changes changes more frequently. +Using stacked branches (Pull Requests) can be helpful for shipping smaller changes more frequently. ### Breaking up a larger change into smaller ones @@ -30,7 +30,7 @@ In the course of implementation you end up performing the following sub-tasks: 3. Implement the frontend part of the feature consuming the API While the feature is considered complete only when all of the subtasks are implemented, reviewed and merged, in many cases it is considered beneficial -to ship each stage of the feature on it's own, potentially behind a feature flag. Not only the risk of merge conflicts with colleagues is reduced, +to ship each stage of the feature on its own, potentially behind a feature flag. Not only the risk of merge conflicts with colleagues is reduced, but also eventual bugs are easier to track down / revert / fix as compared to a single large change. ### More granular (easier) review process @@ -46,42 +46,42 @@ This way it is possible to approve and merge the initial part of a stack (e.g. a Stacking and Virtual Branches are similar in that they allow you to separate code changes / commits into different branches. In both cases, the changes are available in your working directory. -The main difference is that Virtual Branches are **independent** from one another, while stacked branches **depend** on the branch that precedes it. -Because of this, the two features are not mutually exclusive but rather complementary. For example a bugfix change that is unrelated to a feature being developed -can be put in a separate virtual branch. On the other hand a change that depends on a previous change can be put in a stacked branch above the one it depends on. +The main difference is that Virtual Branches are **independent** from one another, while stacked branches **depend** depend on the ones that come before it. +Because of this, the two features are not mutually exclusive but rather complementary. For example a bugfix change that is unrelated to a feature +can be put in a separate virtual branch. On the other hand, a change that depends on a previous change can be put in a stacked branch above the one it depends on. -In fact GitButler implements stacked branches as Virtual Branches that are split into multiple dependent branches which makes for a flexible workflow. +In fact GitButler implements stacked branches as Virtual Branches that are split into multiple dependent branches. ## Workflow By default, virtual branches in the app are simply stacks of one. With version `0.14.0` or newer -you can create a new dependent branch within a lance with the `+` button above the branch name. +you can create a new dependent branch within a lane by clicking the `+` button above the branch name. > The workflow below assumes a GitHub remote. If you are using a different forge, you can still use this functionality but will need to manually create/update the Pull/Merge Requests -1. Creating a new dependent branch forms a new stack within the virtual branch +1. Creating a new dependent branch forms a new stack within the virtual branch. -2. New commits land in the topmost branch of the stack +2. New commits land in the top branch of the stack. -3. Pushing is done for the stack as a whole. Note: The Pull Requests will be created in a way where each branch points to it's predecessor - see [Automatic branch deletion](#automatic-branch-deletion) +3. Pushing is done for the stack as a whole. Note: The Pull Requests will be created in a way where each branch points to its parent - see [Automatic branch deletion](#automatic-branch-deletion) -4. Pull request creation has to be done from the bottom of the stack upwards +4. Pull requests must be created one at a time starting from the bottom of the stack. -5. The PRs will contain a footer with stack information and as you add more PRs it will keep all up to date +5. The PRs will contain a footer with stack information, and as you add more PRs it will keep all up to date. -6. You can drag changes into commits to amend them (e.g. incorporating review feedback) as well as move and squash commits +6. You can drag changes into commits to amend them (e.g. incorporating review feedback) as well as move and squash commits. 8. Review/merge your PRs starting from the bottom up. After a PR/branch from your stack has been merged, it is reflected in the Stack and you should force push to reflect the changes - on the remote as well + on the remote as well. -9. When all branches of a stack have been merged, the stack is complete +9. When all branches of a stack have been merged, the stack is complete. ## GitHub configuration for stacked PRs _TLDR:_ 1. Enable automatic branch deletion [automatic branch deletion](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/managing-the-automatic-deletion-of-branches) - on GitHub + on GitHub. 2. If possible, consider using the the "Merge" strategy when merging PRs. #### Automatic branch deletion @@ -123,14 +123,14 @@ When reviewing a PR in a stack, it is important to be able to view only the chan Of course, in pure Git terms, a stacked branch will contain all the changes from the branches below it. In order to show only the expected Files changed and Commits for PRs in a stack, each PR is created to target the branch below it in the stack. -This is true for all but the bottom-most branch in the stack, which targets the default branch of the repository as usual. +This is true for all but the bottom branch in the stack, which targets the default branch of the repository as usual. > Every branch in the stack contains the commits from the branches below it. -This of course does not mean that a Pull Request should be merged into it's predecessor. -When the bottom-most branch is merged on GitHub, **if** the PR branch is deleted, +This of course does not mean that a Pull Request should be merged into its parent. +When the bottom branch is merged on GitHub, **if** the PR branch is deleted, GitHub will automatically update any PRs that used to target it to target the default branch instead. @@ -162,6 +162,6 @@ A mitigation for this is to rename the branch, push and re-create the Pull Reque #### Accidentally merged a branch into a branch before it (not integrated into main/master yet) Merging of branches in a stack should be done from the bottom up. With the GitHub interface, it is possible to incorrectly merge a Pull Request which is in the middle of the stack. -In this case it will merged in it's predecessor branch. +In this case it will merged in the parent branch. In order to recover from this situation you can simply force push the branches and then re-create the PR that was incorrectly merged.