Skip to content
24 changes: 21 additions & 3 deletions docs/reference/contributing/guidelines/workflow.md
Original file line number Diff line number Diff line change
Expand Up @@ -219,11 +219,29 @@ We use many other labels to summarize the scope and effect of the changes.

- *needs: preceding PR* - This pull request cannot yet be merged because it has a dependency on another pull request that needs to merge first.
- *DO NOT MERGE* - This pull request contains changes that may be in a draft state and submitted purely for review, or may contain breaking changes that have not been considered.
- *devices: 'name'* - The pull request specifically affects the named device(s).
- *component: 'name'* - The pull request specifically affects the named component. Component names follow the structure of Mbed OS (`ble`, `storage`, `tls` and so on).
- *devices: 'name'* - This pull request specifically affects the named device(s).
- *component: 'name'* - This pull request specifically affects the named component. Component names follow the structure of Mbed OS (`ble`, `storage`, `tls` and so on).
- *rollup PR* - This pull request is ready for CI testing, but will instead be brought into a rollup pull request to test multiple pull requests at once.

The following labels summarize the scope of the pull request.

- *scope: bug-fix*.
- *scope: feature*.
- *scope: new-target*.
- *scope: new-target*

#### Rollup pull requests

When Mbed OS has many small, orthogonal pull requests waiting for CI testing to start, maintainers have the option of bundling multiple pull requests into a single pull request referred to as a rollup pull request. Once this rollup pull request passes CI testing and is merged, the bundled pull requests used to build the rollup pull request are also automatically merged.

By the time a pull request is selected to be integrated into a rollup pull requests, it already has a release label and is patiently waiting to start CI testing. Each bundled pull request gains a *rollup PR* label and once the rollup pull request is generated, a comment is also be added to the bundled pull request, informing the bundled pull request's author.

In the event that the rollup pull request fails CI testing, maintainers will identify the problem bundled pull requests, update their statuses, and will provide additional guidance on what went wrong. Critically, if a bundled pull request is updated *while* it is already in a rollup pull request, and the rollup pull request passes CI and is merged, the updated bundled pull request *will not* be automatically merged.

##### How it works

Rollup pull requests take advantage of the exact same process that is used to merge a pull request into master, except that pull requests are mergedin into a freshly rebased temporary branch. All pull requests with the *rollup PR* label are cloned and merged into the temporary branch, and assuming no merge conflicts arise, a pull request is opened with the temporary branch. Once the rollup pull request is merged, all other pull requests that went into building the rollup pull request are also _marked_ as merged because their contents are now a part of master.

Rollup pull requests are a solution to two types of problem: CI testing duration, and semantic conflict problem. The most obvious use of a rollup pull request is to drastically lower the time needed to test many pull requests at once. Best case, maintainers go from needing to put N pull requests through CI, down to only one, drastically lowering the load on CI infrastructure, and helps close pull requests much sooner. The second, more suble, problem that rollup pull requests solve is the case where two pull requests pass testing on their own, but as soon as they join together, the way they interact with each other causes tests to fail. A simple example can be found [here](https://bors.tech/essay/2017/02/02/pitch).

A special case occurs when a bundled pull request is updated while its rollup pull requests is undergoing testing. When a pull request is bundled into a rollup pull request, it's commits become a part of the rollup pull request, at the time that the rollup pull request source branch is created. If the bundled pull requests is updated, its commit history is no longer exactly mirrored in the rollup pull request. If this situation arises, the bundled pull request that was updated _will not_ be automatically marked as merge, because all changes of the updated bundled pull request were not present in the merged rollup pull request.
Copy link
Contributor

@0xc0170 0xc0170 Nov 13, 2018

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

what should happen if this is the case? No action needed from a user or us?

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ah, fair question. If this happens, work will continue in that updated, previously bundled PR.

Will update.