Stacks: Stacked Pull Requests

Mergify Stacks allow you to split your local Git branches in multiple pull requests to make it easier to split you work in small atomic parts.

The conventional GitHub pull request model operates on a branch-based system where each branch corresponds to one pull request.

As more commits are added to a branch and pushed, the associated pull request expands. This continual growth can complicate the review process, making it challenging for reviewers as the code base increases. Moreover, this model often discourages the division of work into atomic, manageable commits.

The concept of Stacks addresses this issue by breaking down work into incremental, reviewable steps. This structure not only simplifies the review process but also enhances the digestibility of changes for teammates.

Furthermore, should a rollback be necessary, it’s far simpler and less disruptive to revert a single, small pull request rather than an entire branch of accumulated changes.

Mergify Stacks retains the familiar branch model used in Git while innovating on how pull requests are handled. Instead of opening one pull request for an entire branch, Mergify Stacks opens a separate pull request for each commit.

This approach allows developers to maintain all their changes within a single branch while effectively segmenting their work into smaller, more manageable parts. Each part is easier to review and quicker to integrate, streamlining the development process and enhancing overall efficiency.

When a commit needs to be changed, git rebase --interactive can be used to change the content of the branch. Mergify Stacks automatically synchronize your branch to the pull requests.

This means that there is no need to learn any new tool to manage your Mergify Stacks: they are just regular Git branches.

This process ensures that developers don’t have to tediously update each individual pull request manually. Everything is managed under the hood by Mergify Stacks, from the commit level to the PR level.

The automated nature of this approach minimizes the chances of human error—like missing a pull request update or misapplying a change. Developers maintain the freedom and flexibility of the Git interactive rebase, allowing for granular and precise changes to commits.

Begin by installing the Mergify CLI using pip:

Linux:

python3 -m pip install --user mergify-cli

MacOS:

brew install pipx
pipx install mergify-cli

To use Mergify CLI for creating stacked pull requests in your repository, follow these steps:

1. Execute the following command to set up the commit-msg hook:

mergify stack --setup

2. For GitHub API access, Mergify CLI requires a GitHub OAuth token. If you have the gh client authenticated, Mergify CLI will seamlessly fetch the token. If not, create a personal access token with necessary permissions and set it as an environment variable (GITHUB_TOKEN). You can also provide it directly using the --token parameter.

1. Spawn a branch and introduce your changes.

2. Commit the changes. If Mergify CLI is correctly configured, your commit message will automatically contain the Change-Id.

3. In case you committed before initializing Mergify CLI, use git rebase <base-branch> -i to reword commits and automatically embed the Change-Id.

4. To construct the stack, run:

mergify stack

Mergify CLI will manage the creation of individual pull requests for every commit in your feature branch. This structured approach ensures smooth and error-free management of changes and reviews.

Inevitably, there will be times when you’ll need to modify or refine your pull requests—perhaps due to feedback from a code review or just a late realization. Mergify CLI streamlines this process, ensuring your stacked pull requests are always in sync with your latest changes.

1. Stay in Your Feature Branch: The beauty of stacked PRs lies in their granular structure. Always make sure you are working within the specific feature branch where the relevant commits reside.

2. Modifying Commits: To update or modify commits inside your branch:

   • Use the interactive rebase feature of Git:

     git rebase --interactive <base-branch>
     

   • Within the interactive rebase session, you can:

     • pick to retain a commit.
     • reword to change a commit message.
     • edit to modify the content of a commit.
     • squash to combine the commit with the previous one.
     • drop to remove a commit entirely.

   Make your desired changes and save. This action will reapply your commits on top of the base branch, incorporating the changes you’ve made.

3. Pushing Updated Stacked PRs: Once you’ve made all the necessary modifications to your branch and are satisfied with the changes, call the Mergify CLI with the stack command:

   mergify stack
   

   This command will push your modified commits and update the corresponding pull requests on GitHub. Mergify CLI intelligently keeps track of the relationships between your commits and the pull requests, ensuring everything remains synchronized.