This document provides information on the Cascading Auto-Merge extension to the open source Probot-auto-merge app.
Merging release branches based on their semantic versioning, similar to Bitbuckets 'Automatic branch merging'.
The Cascading Auto Merge feature is applicable per repository, it can be enabled on branch prefixes and supports semantic versioning.
The open source probot-auto-merge solution
has the core Auto Merge capability with fine grained control on the enablement / trigger options, but it
does not currently support the cascading auto-merge, the way BitBucket Auto Merge
provides it. That is where this cascading auto-merge extension comes in.
For detailed setup information please see the SETUP.md file.
To explain the Cascading Auto Merge functionality a little bit more detailed, I'll give some example.
-
Lets say an organization has the following release branch structure in their Repository.
Branches master development release/0.1 release/1.1-rc.1 release/1.1 release/1.2 release/2.0 release/2.0.1-alpha release/2.0.1-beta release/2.0.1-beta.1
-
A developer makes a change to the release/1.1 branch and issues a PR against the development branch, requesting at least one approval.
-
With the Cascading Auto Merge functionality support the following should happen.
Up on PR approval, the release/1.1 branch gets auto-merged into the development branch and in addition the release/1.1 branch gets forward auto-merged in to subsequent releases based on their semantic version order.
This sample output should demonstrate the expected GitHub behaviour
-
In the original GitHub PR you will see comments for each subsequent cascading merge PR, including links to these PRs, providing a full audit trail of automated merges.
Below is a sample output of a test run.
top ⬆️
This is a list that highlights some of the features for each implementation.
| # | Features | BitBucket | Probot-Auto-Merge | Notes |
|---|---|---|---|---|
| 1 | Automatic merging is off by default | ✅ | ✅ | |
| 2 | Commit messages will indicate a merge was automatic | ✅ | ✅ | |
| 3 | There are audit log entries for automatic merges | ✅ | ✅ | Each Merge is based on a PR |
| 4 | Notifications are sent when merges succeed or fail | ✅ | ✅ | Utilizing standard GitHub behavior |
| 5 | Cascading Branch merging | ✅ | ✅ | |
| 6 | Only branches matching the name of the pull request target are added into the merge path | ✅ | ✅ | branch name prefix |
| 7 | Custom activation of AutoMerge per Branch | ✅ | GitHub Labels | |
| 8 | Fine grained 'Approver' rules | ✅ |
top ⬆️
The following will give some examples on the supported semantic versions
Reference: Semantic Versioning
- MAJOR version when you make incompatible API changes
- MINOR version when you add functionality in a backwards compatible manner
- PATCH version when you make backwards compatible bug fixes
These are available as extensions to the MAJOR.MINOR.PATCH format.
| Extensions | + Version |
|---|---|
| alpha | alpha.1 |
| beta | beta.1 |
| rc | rc.1 |
The Branch-Prefix is specific to our implementation
In these examples we omit the Branch-Prefix
| Example |
|---|
| 1.1.0 < 1.1.2 < 1.2.0 < 1.2.1 < 1.3.0 < 2.0.0 |
| Example |
|---|
| 1.0.0-alpha < 1.0.0-alpha.1 < 1.0.0-beta < 1.0.0-beta.2 < 1.0.0-beta.11 < 1.0.0-rc.1 < 1.0.0 |
- release/1.1.0
- release/1.2.0-beta
- feature/1.1.0-alpha.1
top ⬆️
The following is a little bit like a Rules engine, we have our facts (create, merge), that in combination define certain conditions and the determined outcome of these conditions form a rule. The table describes the core rules.
With this definition we can predict the outcome of sample Merge-Scenarios.
✅ success
❌ failed
| # | Original PR | Cascading PR | Condition | Actions | ||||
|---|---|---|---|---|---|---|---|---|
| create | merge | create | merge | Issue | Cascading-Auto-Merge | Notes | ||
| 1 | ✅ | ✅ | ✅ | ✅ | NA | none | continue | All good nothing to report |
| 2 | ✅ | ✅ | ✅ | ❌ | NA | ✅ | stop | |
| 3 | ✅ | ✅ | ❌ | NA | A PR already exists | ✅ | stop | a PR already exists cannot create new one |
| 4 | ✅ | ✅ | ❌ | NA | No commits between releases | none | continue | commits might have already been merged |
| 5 | ✅ | ❌ | NA | NA | Original PR merge conflict | none | NA | Original PR contains all info |
| 6 | ❌ | NA | NA | NA | Nothing even happened | none | NA | Auto-Merge not triggered |
A couple of merge scenarios and the resulting behavior of the cascading auto-merge feature.
- master
- development
- release/0.1 < release/1.1-rc.1 < release/1.1 < release/1.2 < release/2.0 < release/2.0.1-alpha < release/2.0.1-beta < release/2.0.1-beta.1
Note: omitting the prefix, 'release'
✅ successful merge
❌ merge conflict
| # | scenario | description | Parent PR merged status | cascading PR merge status | Notification location | Notes |
|---|---|---|---|---|---|---|
| 1 | 1.1 -> development | standard Git workflow | ✅ | ✅ | In Original PR (msg: created cascading PR # ) | all good, no additional action required |
| 2 | 1.1 -> development | standard Git workflow | ✅ | ❌ | In Original PR (msg: created cascading PR #), create failed merge issue | cascading merge halts, completed merges remain |
| 3 | 1.1 -> development | standard Git workflow | ❌ | ❌ | In Original PR, (msg: merge conflict) | no cascading merge triggered |
| 4 | 1.1 -> 1.2 | release to release | ✅ | ✅ | In Original PR (msg: no commit for PR) | merge base (1.2) is in cascading merge, App will try to execute twice, safe |
| 5 | 1.1 -> 1.2 | release to release | ✅ | ❌ | In Original PR (msg: created cascading PR #), create failed merge issue | cascading merge halts, completed merges remain |
| 6 | 1.1 -> 1.2 | release to release | ❌ | ❌ | In Original PR (msg: merge conflict) | no cascading merge triggered |
| 7 | patch -> 1.1 | standard Git workflow | ✅ | ❌ | In Original PR, no comment about cascading PR | auto-merge triggers on 'head-branch' name only, if you require cascading merges, combine with scenario #4 |
| 8 | 2.0.1-beta.1 -> development | standard Git workflow | ✅ | ❌ | In Original PR, no comment about cascading PR | is latest release, no subsequent releases |
| 9 | 1.2 -> 1.1 | back porting a change | ✅ | ✅ | In Original PR (msg: created cascading PR #) | cascading merge triggered, subsequent release will be merged, no different from merging to 'development' |
top ⬆️