Stacked Pull Requests

Introduction

Mergify CLI is a powerful tool designed to simplify and automate the creation and management of stacked pull requests on GitHub. Before diving into its functionalities, let's grasp the concept of stacked pull requests and why they matter.

Understanding Stacked Pull Requests

In the world of development, a common scenario is having a feature branch with multiple commits that are sequentially dependent on each other. For instance, if you have a branch named feature with three commits: A, B, and C, creating stacked pull requests manually on GitHub would require:

1. A branch feature-A for commit A with a pull request based on main.
2. A branch feature-B for commit B with a pull request based on feature-A.
3. A branch feature-C for commit C with a pull request based on feature-B.

While this method ensures structured and granular reviews, the native GitHub approach has its challenges. If a modification is made to commit A, all subsequent branches and their associated pull requests need manual updates — a tedious and error-prone task.

Mergify Stacked Pull Requests

With a mechanism similar to code review tools like Gerrit, Mergify CLI introduces a unique identifier, named Change-Id, into the commit message. This identifier is managed via a git commit-msg hook, ensuring systematic tracking of changes. Here's a glimpse of the Change-Id:

1
Change-Id: I7074fdf5e24e2d4de721936260e4b962532c9735

The tool utilizes the GitHub API to manage the pull requests, ensuring that your local git repository remains pristine.

Benefits of This Approach

• Streamlined Workflow: This process ensures that developers don't have to tediously update each individual pull request manually. Everything is managed under the hood by Mergify CLI, from the commit level to the PR level.

• Reduced Errors: The automated nature of this approach minimizes the chances of human error—like missing a pull request update or misapplying a change.

• Flexibility: Developers maintain the freedom and flexibility of the Git interactive rebase, allowing for granular and precise changes to commits.

Setting Up Mergify CLI

Installation

Begin by installing the Mergify CLI using pip:

1
pip install mergify_cli

Configuration

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:

1
mergify stack --setup

2. Identify your trunk branch. This branch acts as the foundation for your stacked pull requests. You can configure it using:

1
git config --add mergify-cli.stack-trunk origin/branch-name

Alternatively, you can specify the trunk branch using the --trunk parameter.

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

Creating Stacked Pull Requests

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:

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

Updating Stacked Pull Requests

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:

     Bash

     1
     git rebase --interactive <base-branch>

     Copy

   • 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:

   Bash

   1
   mergify stack

   Copy

   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.