<h1 class="title">Merge Bot</h1> <a name="odoo-workflow"></a> <h2>Odoo workflow</h2> <p>The sticky branches are protected on the github odoo project to restrict push for the Merge Bot (MB) only.</p> <p>The MB only works with PR's using the github API.</p> <ol class="arabic simple"> <li>When a PR is created the github notifies the MB. The MB labels the PR as 'seen 🙂' on github <a class="footnote-reference" href="#id4" id="id1">[1]</a>.</li> <li>Once the PR github statuses are green <a class="footnote-reference" href="#id5" id="id2">[2]</a> , the MB labels the PR as 'CI 🤖'.</li> <li>When a reviewer, known by the MB, approves the PR, the MB labels that PR as 'r+ 👌'.</li> <li>At this moment, MB tries to merge the PR and labels the PR with 'merging 👷'.</li> <li>If the merge is successfull, MB labels it 'merged 🎉', removes the label 'merging 👷' and closes the PR. A message from MB gives a link to the merge's commit <a class="footnote-reference" href="#id6" id="id3">[3]</a>.</li> </ol> <p>If an error occurs during the step 4, MB labels the PR with 'error 🙅' and adds a message in the conversion stating what kind of error. For example 'Unable to stage PR (merge conflict)'.</p> <p>If a new commit is pushed in the PR, the process starts again from the begining.</p> <p>It's possible to interact with the MB by the way of github messages containing <a class="reference internal" href="#commands">Commands</a>. The message must start with the MB name (for instance 'robodoo').</p> <table class="docutils footnote" frame="void" id="id4" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#id1">[1]</a></td><td>Any activity on a PR the MB hasn't seen yet will bring it to the MB's attention. e.g a comment on a PR.</td></tr> </tbody> </table> <table class="docutils footnote" frame="void" id="id5" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#id2">[2]</a></td><td>At this moment the statuses are: Runbot build is green and CLA is signed if needed. The expected statuses may change in the future.</td></tr> </tbody> </table> <table class="docutils footnote" frame="void" id="id6" rules="none"> <colgroup><col class="label" /><col /></colgroup> <tbody valign="top"> <tr><td class="label"><a class="fn-backref" href="#id3">[3]</a></td><td>If a PR contains only one commit, the PR is rebased and the commit is fast forwarded. With more than one commit, the PR is rebased and the commits are merged with a merge commit. When one wants to avoid the rebase, 'rebase-' command should be used.</td></tr> </tbody> </table> <a name="setup"></a> <h2>Setup</h2> <ul> <li><p class="first">Setup a project with relevant repositories and branches the bot should manage (e.g. odoo/odoo and 10.0).</p> </li> <li><p class="first">Set up reviewers (github_login + boolean flag on partners).</p> </li> <li><p class="first">Add &quot;Issue comments&quot;, &quot;Pull request reviews&quot;, &quot;Pull requests&quot; and &quot;Statuses&quot; webhooks to managed repositories.</p> </li> <li><p class="first">If applicable, add &quot;Statuses&quot; webhook to the <em>source</em> repositories.</p> <p>Github does not seem to send statuses cross-repository when commits get transmigrated so if a user creates a branch in odoo-dev/odoo, waits for CI to run then creates a PR targeted to odoo/odoo the PR will never get status-checked (unless we modify runbot to re-send statuses on pull_request webhook).</p> </li> </ul> <a name="working-principles"></a> <h2>Working Principles</h2> <p>Useful information (new PRs, CI, comments, ...) is pushed to the MB via webhooks. Most of the staging work is performed via a cron job:</p> <ol class="arabic"> <li><p class="first">for each active staging, check if they are done</p> <ol class="arabic"> <li><p class="first">if successful</p> <ul class="simple"> <li><code>push --ff</code> to target branches</li> <li>close PRs</li> </ul> </li> <li><p class="first">if only one batch, mark as failed</p> <p>for batches of multiple PRs, the MB attempts to infer which specific PR failed</p> </li> <li><p class="first">otherwise split staging in 2 (bisection search of problematic batch)</p> </li> </ol> </li> <li><p class="first">for each branch with no active staging</p> <ul class="simple"> <li>if there are inactive stagings, stage one of them</li> <li>otherwise look for batches targeted to that PR (PRs grouped by label with branch as target)</li> <li>attempt staging<ol class="arabic"> <li>reset temp branches (one per repo) to corresponding targets</li> <li>merge each batch's PR into the relevant temp branch<ul> <li>on merge failure, mark PRs as failed</li> </ul> </li> <li>once no more batch or limit reached, reset staging branches to tmp</li> <li>mark staging as active</li> </ol> </li> </ul> </li> </ol> <a name="commands"></a> <h2>Commands</h2> <p>A command string is a line starting with the mergebot's name and followed by various commands. Self-reviewers count as reviewers for the purpose of their own PRs, but delegate reviewers don't.</p> <dl class="docutils"> <dt>retry</dt> <dd><p class="first">resets a PR in error mode to ready for staging</p> <p class="last">can be used by a reviewer or the PR author to re-stage the PR after it's been updated or the target has been updated &amp; fixed.</p> </dd> <dt>r(review)+</dt> <dd><p class="first">approves a PR, can be used by a reviewer or delegate reviewer</p> <p class="last">submitting an &quot;approve&quot; review implicitly r+'s the PR</p> </dd> <dt>r(eview)-</dt> <dd>removes approval from a PR, allows un-reviewing a PR in error (staging failed) so it can be updated and re-submitted</dd> </dl> <dl class="docutils"> <dt>delegate+/delegate=&lt;users&gt;</dt> <dd>adds either PR author or the specified (github) users as authorised reviewers for this PR. <code>&lt;users&gt;</code> is a comma-separated list of github usernames (no &#64;), can be used by reviewers</dd> <dt>p(riority)=2|1|0</dt> <dd>sets the priority to normal (2), pressing (1) or urgent (0), lower-priority PRs are selected first and batched together, can be used by reviewers</dd> <dt>rebase-</dt> <dd>the default merge mode is to rebase and merge the PR into the target, however for some situations this is not suitable and a regular merge is necessary; this command toggles rebasing mode off (and thus back to a regular merge)</dd> </dl> <a name="structure"></a> <h2>Structure</h2> <p>A <em>project</em> is used to manage multiple <em>repositories</em> across many <em>branches</em>.</p> <p>Each <em>PR</em> targets a specific branch in a specific repository.</p> <p>A <em>batch</em> is a number of co-dependent PRs, PRs which are assumed to depend on one another (the exact relationship is irrelevant) and thus always need to be batched together. Batches are normally created on the fly during staging.</p> <p>A <em>staging</em> is a number of batches (up to 8 by default) which will be tested together, and split if CI fails. Each staging applies to a single <em>branch</em> the target) across all managed repositories. Stagings can be active (currently live on the various staging branches) or inactive (to be staged later, generally as a result of splitting a failed staging).</p> <a name="notes"></a> <h2>Notes</h2> <ul class="simple"> <li>When looking for stageable batches, priority is taken in account and isolating e.g. if there's a single high-priority PR, low-priority PRs are ignored completely and only that will be staged on its own</li> <li>Reviewers are set up on partners so we can e.g. have author-tracking &amp; delegate reviewers without needing to create proper users for every contributor.</li> <li>MB collates statuses on commits independently from other objects, so a commit getting CI'd in odoo-dev/odoo then made into a PR on odoo/odoo should be correctly interpreted assuming odoo-dev/odoo sent its statuses to the MB.</li> <li>Github does not support transactional sequences of API calls, so it's possible that &quot;intermediate&quot; staging states are visible &amp; have to be rollbacked e.g. a staging succeeds in a 2-repo scenario, A.{target} is ff-d to A.{staging}, then B.{target}'s ff to B.{staging} fails, we have to rollback A.{target}.</li> <li>Co-dependence is currently inferred through <em>labels</em>, which is a pair of <code>{repo}:{branchname}</code> e.g. odoo-dev:11.0-pr-flanker-jke. If this label is present in a PR to A and a PR to B, these two PRs will be collected into a single batch to ensure they always get batched (and failed) together.</li> </ul> <a name="previous-work"></a> <h2>Previous Work</h2> <a name="bors-ng"></a> <h3>bors-ng</h3> <ul class="simple"> <li>r+: accept (only for trusted reviewers)</li> <li>r-: unaccept</li> <li>r=users...: accept on behalf of users</li> <li>delegate+: allows author to self-review</li> <li>delegate=users...: allow non-reviewers users to review</li> <li>try: stage build (to separate branch) but don't merge on succes</li> </ul> <a name="why-not-bors-ng"></a> <h4>Why not bors-ng</h4> <ul class="simple"> <li>no concurrent staging (can only stage one target at a time)</li> <li>can't do co-dependent repositories/multi-repo staging</li> <li>cancels/forgets r+'d branches on FF failure (emergency pushes) instead of re-staging</li> </ul> <a name="homu"></a> <h3>homu</h3> <p>Additionally to bors-ng's:</p> <ul class="simple"> <li>SHA option on r+/r=, guards</li> <li>p=NUMBER: set priority (unclear if best = low/high)</li> <li>rollup/rollup-: should be default</li> <li>retry: re-attempt PR (flaky?)</li> <li>delegate-: remove delegate+/delegate=</li> <li>force: ???</li> <li>clean: ???</li> </ul>