Commits

Pierre-Yves David  committed bf76d13

add a README explaining the current vision

  • Participants
  • Parent commits bab2a84

Comments (0)

Files changed (1)

File reviewbot/README

+Rational
+========
+
+The ultimate goal of this set of tools is to bring back together the good old
+email based work flow and the more modern repository based work flow. Both have
+strength and weakness, lets try to get the best of the two worlds
+
+Core idea
+===================================
+
+1. The main submission and comment medium should stay the mailing list.
+
+2. As much data as possible should be contained into a Mercurial repository
+
+3. Obsolescence Markers are the future of collaboration, the review process
+   should take advantage of them as much as possible and create missing one.
+
+Target feature overview
+====================================
+
+1. Contributors can patchbomb the mailing list
+
+2. The bot grab the whole series from the list, process it and notify the list
+   back.
+
+3. Reviewer can easily retrieve patches/series content.
+
+4. Contributers and reviewers can easily check series/patches states.
+
+5. The bots track the main and satellite repo for updated state.
+
+6. The bots track the mailing list for:
+   - comments
+   - newer version
+
+7. Automatically suggest reviewer by looking at files touched by a patches and expert on those file.
+
+Detailed Capabilities and step
+==============================
+
+a. Grabbing new patches from the list
+--------------------------------------
+
+The REVIEWBOT process incoming emails on the list. Detect patches and are able to
+group them in consistent series. The current patchbot is already able to group
+such series. And augmenting patchwork to make patches series Cristal clear is
+trivial.
+
+The REVIEWBOT will first focus on handle most patches. We can expect the main
+flow of patches to comes from a small set of regular contributors up to date
+Mercurial. We already have multiple other generic tool to detect patches sent
+by seasonal contributors using less standardised tooling. Moreover, if
+REVIEWBOT are obvious enough on patches it handles, the non-picked
+one will stand out.
+
+b. Processing grabbed series
+--------------------------------------
+
+Once a patches series is detected, REVIEWBOT will:
+
+1. Record that the patches and series exists
+
+2. Turns them into real changesets in a real repository. There is two multiple
+   option for this.
+
+The most obvious way to do this is to `hg import` the patches. We can have
+fairy solid application process:
+
+1. Use parent information for the root changeset of the series to apply patches
+   where it was created.
+
+2. We can revive "pvec" to apply the patch on closest known parent.
+
+3. We MUST create obsolescence marker from patch node to actually created
+   changeset. (we should also consider transmitting extra content to get
+   --exact to work)
+
+4. We can automatically rebase the result on the latest head.
+
+5. At some point we may want to transmit obsolescence markers from the
+   contributor through patch bomb.
+
+However, the most effective and least distributive way to get real changeset
+for submitted review is to pull them from the contributors repo. We should be
+able to extend the patchbombed changeset to optionality includes a url to pull
+from a public repository. Most active/motivated contributors would then setup
+such repo and configure they patchbomb extension to includes such links.
+
+The main advantage of the pull based approach is that it grantee that the
+changeset in the review repo are the very same as the one in the contributors
+repo, preventing useless divergence situation. It also helps propagation of
+obsolescence markers.
+
+Note that current bookmark behavior will cause some issue if REVIEWBOT pull
+from
+arbitrary repository.
+
+c. User notification
+--------------------------------------
+
+Once series has been processed, REVIEWBOT send a reply to the series (on email by series). This reply contains:
+
+1. Thanks for your submission message,
+2. URL to the state of its review,
+3. Results of check code runs,
+4. CC of good reviewer candidates (from touched file history),
+5. Superseding information if the series is a new version,
+6. Potential other errors from application, rebase, code freeze violation,
+7. Instruction to retrieve the series content for reviewers,
+8. Instruction to pull the new changeset if the hash changed during application.
+9. May also includes test run at some point
+
+Incomplete patches series will be put on hold for some time. After a some time
+out. The failure to process the series will be notified to the user.
+
+d. Reviewer Retrieves patches series
+--------------------------------------
+
+Two ways are offered to retrieve patches:
+
+1. Plain patch from http. reviewers are able to use `hg import
+   http://review.foo/patches/<hash>` like comment to get a patch. This is very
+   easy step to implement (Actually the only one done for now) and greatly
+   lower the entry barrier for new reviewers.
+
+2. As we have actual changesets in an actual repository, Reviewers can use `hg
+   pull --rev X from the review repository`. Direct pulling present also the
+   advantage to (a) make sure we do not create extra changeset (avoiding
+   useless divergence) (b) transmits obsolescence markers, purging older
+   version of the same patches.
+
+Ease retrieving of patch important to help new reviewers. If they do not have to setup complicated script to retrieve patch from they mailbox this is huge win.
+
+e. Detecting queued/published patches
+--------------------------------------
+
+If all people queuing patches properly creates obsolescence markers, REVIEWBOT
+can detect when any of the queuers repo contains a changeset that succeed to a
+submitted one. From there we can automatically change state of the patches and
+notify by email that the patch have been queued.
+
+Same applies when the patches becomes public.
+
+f. Detecting Newer version
+--------------------------------------
+
+When using direct pulling approach REVIEWBOT can directly use the obsolescence
+graph to detect newer version of a patches.
+
+When using the patchbomb email only we can reuse the PATCHBOT logic to detect
+resend from V2 flags. In that case, REVIEWBOT should create obsmarkers between
+older series and newer series.
+
+Architecture
+==============================
+
+This MUST NOT be a gigantic blob of code handling all possibles feature. This
+Must be a modular set of small tools all dedicated to a simple task. Each small
+tool would ideally replaced by a more serious and standard tool dedicated to
+each tasks.
+
+Envisioned module are:
+
+Email processing
+----------------------
+
+A script in charge of reading incoming email and turning them into an atomic
+addition of changeset and obsolescence markers to the repo.
+
+It probably also record some information linking emails to nodes.
+
+Series/draft changeset tracking
+-------------------------------
+
+A set of hooks in charge of processing transaction that adds changeset,
+obsmarker and phases to the repo. They track and update persistent state for
+element currently in review.
+
+"Review UI"
+------------------------------
+
+In charge of presenting review state to the users and sending email.
+
+