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