1# Contribute Bot Auto-Merge Design 2 3Author: [@zombiezen][]<br> 4Date: 2018-12-17<br> 5Part of [#687][] 6 7[@zombiezen]: https://github.com/zombiezen 8[#687]: https://github.com/google/go-cloud/issues/687 9 10## Objective 11 12The maintainers of the Go CDK want pull requests merged in as quickly as they 13can be merged after receiving approvals, assuming there are no test breakages or 14merge conflicts. Currently, merging requires a manual process: 15 16``` 17while branch is not up-to-date with master { 18 press update branch button 19 wait for Travis run to finish 20} 21click squash-and-merge 22``` 23 24This loop is especially expensive the longer the waiting is, since it increases 25the likelihood that the branch is not up-to-date and thus causing the cycle to 26increase iterations (more waiting!). 27 28The objective of this design is to reduce the amount of maintainer [toil][] in 29this process. 30 31[toil]: https://landing.google.com/sre/sre-book/chapters/eliminating-toil/ 32 33## Overview 34 35To reduce maintainer toil, this document proposes a new set of interactions for 36Contribute Bot. If a user writes a comment on a pull request that starts with 37the text "/merge", Contribute Bot will: 38 391. Verify that the commenter has `write` or `admin` access to the repository. 40 If they do not, do not proceed and leave an error comment on the PR. 412. Verify that the pull request has the approvals required by the 42 [GitHub branch protections][required reviews]. If it does not, do not 43 proceed and leave an error comment on the PR. 443. Verify that there are no other commits on the pull request branch since the 45 last approved commit (or a manually entered commit hash entered by the 46 commenter) other than those created by Contribute Bot. If such commits 47 exist, then do not proceed and leave a comment on the PR mentioning that 48 "/merge COMMITHASH" will bypass this. While this is stricter than what the 49 branch protections might allow, it avoids accidentally merging in unreviewed 50 changes. 514. Leave a comment on the PR to the effect that Contribute Bot has received the 52 request and that it will report back if it is unable to merge the PR. 535. If the pull request is not up to date with the changes on the base branch, 54 then create a merge commit on the pull request branch. If the merge commit 55 cannot be created due to merge conflicts, then stop trying to merge the PR 56 and make an error comment on the PR. 576. Wait for any necessary check runs to report completion. If any report 58 failure, then stop trying to merge the PR and make an error comment on the 59 PR. 607. Merge the pull request using the project's allowed merge method (`squash` 61 for Go CDK and Wire), using the title and body of the pull request (the 62 first comment) as the commit message in the case of `merge` or `squash`. 63 64Multiple pull requests may be requested to be merged at the same time. In this 65case, Contribute Bot will hold off on proceeding through Steps 4-6 until the 66merge requests made earlier have either been merged or stopped due to errors. 67 68[required reviews]: https://help.github.com/articles/about-required-reviews-for-pull-requests/ 69 70## Detailed Design 71 72TODO 73 74## Security Considerations 75 76Contribute Bot will need the following new permissions: 77 78- [Read & write repository contents][] (writing the merge commit) 79- [Read repository administration][] (identifying which check runs are 80 necessary to pass branch protections) 81 82[Read repository administration]: https://developer.github.com/v3/apps/permissions/#permission-on-administration 83[Read & write repository contents]: https://developer.github.com/v3/apps/permissions/#permission-on-contents 84 85## Testing Plan 86 87This will be tested just like Contribute Bot is tested currently: by running 88manual tests against a sandbox repository. 89 90## Alternatives Considered 91 92There are a handful of different off-the-shelf solutions that act as GitHub 93merge bots, but each would need to be customized to suit our needs. It would 94also increase the number of systems that the Go CDK contributors would need to 95maintain and monitor. 96 97This could also be implemented as a tool that each maintainer individually runs. 98However, this would require an always-on connection and additional 99per-maintainer burden, versus having a centralized implementation that's already 100connected and properly authorized to the project. Having a centralized service 101merge the pull requests also reduces load on Travis, since it can hold off on 102doing unnecessary merges while other pull requests are queued for merging. 103