[IMP] runbot_merge: readme updates

runbot_merge/README.rst

@@ -7,9 +7,8 @@ Setup
 * Setup a project with relevant repositories and branches the bot
   should manage (e.g. odoo/odoo and 10.0).
 * Set up reviewers (github_login + boolean flag on partners).
-* Sync PRs.
-* Add "Issue comments","Pull requests" and "Statuses" webhooks to
-  managed repositories.
+* Add "Issue comments", "Pull request reviews", "Pull requests" and
+  "Statuses" webhooks to managed repositories.
 * If applicable, add "Statuses" webhook to the *source* repositories.
 
   Github does not seem to send statuses cross-repository when commits
@@ -71,15 +70,15 @@ retry
 r(review)+
   approves a PR, can be used by a reviewer or delegate reviewer
 
-r(eview)-
-  removes approval from a PR, currently only active for PRs in error
-  mode: unclear what should happen if a PR got unapproved while in
-  staging (cancel staging?), can be used by a reviewer or the PR
-  author
+  submitting an "approve" review implicitly r+'s the PR
 
-squash+/squash-
-  marks the PR as squash or merge, can override squash inference or a
-  previous squash command, can only be used by reviewers
+r(eview)-
+  removes approval from a PR, allows un-reviewing a PR in error (staging
+  failed) so it can be updated and re-submitted
+
+.. squash+/squash-
+..   marks the PR as squash or merge, can override squash inference or a
+..   previous squash command, can only be used by reviewers
 
 delegate+/delegate=<users>
   adds either PR author or the specified (github) users as authorised
@@ -91,32 +90,11 @@ p(riority)=2|1|0
   lower-priority PRs are selected first and batched together, can be
   used by reviewers
 
-  currently only used for staging, but p=0 could cancel an active
-  staging to force staging the specific PR and ignore CI on the PR
-  itself? AKA pr=0 would cancel a pending staging and ignore
-  (non-error) state? Q: what of co-dependent PRs, staging currently
-  looks for co-dependent PRs where all are ready, could be something
-  along the lines of::
-
-      (any(priority = 0) and every(state != error)) or every(state = ready)
-
-TODO
-----
-
-* PR edition (retarget, title/message)
-* Ability to disable/ignore branches in runbot (tmp branches where
-  staging is being built)
-* What happens when cancelling staging during bisection
-
-TODO?
------
-
-* Prioritize urgent PRs over existing batches?
-* Make autosquash dynamic? Currently PR marked as squash if only 1
-  commit on creation, this is not changed if more commits are added.
-* Use actual GH reviews? Currently only PR comments count.
-* Rebase? Not sure what use that would have & would need to be done by
-  hand
+rebase-
+  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)
 
 Structure
 ---------
@@ -145,7 +123,7 @@ Notes
   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
 * Reviewers are set up on partners so we can e.g. have author-tracking
-  & deletate reviewers without needing to create proper users for
+  & delegate reviewers without needing to create proper users for
   every contributor.
 * 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
@@ -156,13 +134,11 @@ Notes
   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}.
-* Batches & stagings are non-permanent, they are deleted after success
-  or failure.
 * Co-dependence is currently inferred through *labels*, which is a
-  pair of ``{login}:{branchname}``
-  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.
+  pair of ``{repo}:{branchname}`` 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.
 
 Previous Work
 -------------
@@ -184,7 +160,6 @@ Why not bors-ng
 * can't do co-dependent repositories/multi-repo staging
 * cancels/forgets r+'d branches on FF failure (emergency pushes)
   instead of re-staging
-* unclear whether prioritisation supported
 
 homu
 ~~~~