Skip to content

Commit

Permalink
Fix some grammar in stacked branches page
Browse files Browse the repository at this point in the history
  • Loading branch information
mtsgrd committed Nov 26, 2024
1 parent 96afc00 commit 9540aba
Showing 1 changed file with 21 additions and 21 deletions.
42 changes: 21 additions & 21 deletions content/docs/features/stacked-branches.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand All @@ -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

Expand All @@ -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
Expand All @@ -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.

<ImageSection src="/img/docs/stacked-branches/11_overview.jpg" />

## 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.

<ImageSection src="/img/docs/stacked-branches/1_creating_stack.jpg" />

2. New commits land in the topmost branch of the stack
2. New commits land in the top branch of the stack.

<ImageSection src="/img/docs/stacked-branches/2_new_commits.jpg" />

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)

<ImageSection src="/img/docs/stacked-branches/3_push_all.jpg" />

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.

<ImageSection src="/img/docs/stacked-branches/4_create_pr.jpg" />

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.

<ImageSection src="/img/docs/stacked-branches/5_pr_footer.jpg" />

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.

<ImageSection
src="/img/docs/stacked-branches/6_modify_commits-amend.jpg"
Expand All @@ -102,19 +102,19 @@ you can create a new dependent branch within a lance with the `+` button above t
<ImageSection src="/img/docs/stacked-branches/7_move_to_vb.jpg" />

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.

<ImageSection src="/img/docs/stacked-branches/8_merging-1.jpg" />
<ImageSection src="/img/docs/stacked-branches/8_merging-2.jpg" />

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
Expand All @@ -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.

<ImageSection src="/img/docs/stacked-branches/9_pr_heads.jpg" />

> 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.

<ImageSection src="/img/docs/stacked-branches/10_branch_deletion.jpg" />
Expand Down Expand Up @@ -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.

0 comments on commit 9540aba

Please sign in to comment.