REVU2Spec

Summary

REVU2 is a tool for assisting MOTUs in reviewing packages. Packages are created mainly by contributors, but also automatically by other tools.

In the following revu refers to the 2nd implementation of REVU, sometimes called REVU2. http://revu.tauware.de runs a prototype implementation.

Rationale

It is a bit hard for new contributors to show what they know and to improve their packaging skills. It is also time consuming for MOTUs to check packages made by contributors. These processes need to be streamlined in order to facilitate better throughput.

Glossary

  • Contributor refers to a person who is providing a source package (candidate) to revu but is not otherwise permitted to upload to Ubuntu.

  • Candidate is a source package uploaded to revu by a contributor

  • Candidate Series is a set of Candidates of which the last one is aimed to be uploaded to the archive.

Scope and Use cases

  • Daniela uploads a new package to revu, and wants it to be in Ubuntu. MOTU Bob reviews it, checking it intensively. It turns out that the package is fine, so he advocates it. The package gets into to the "pending upload queue" and is eventually uploaded by a MOTU. The changes list for the distribution is monitored and the package is removed from the pending upload queue automatically.
  • Jennifer uploads a new package, and it turns out to be bad, MOTU Andrea will review the package and add a comment to this package with an explanation as to why the package is bad. MOTU Andrea will veto the package.
  • Caroline uploads an improvement to an existing package. Since this upload is a small change to an existing package in the ubuntu archive, it is more convenient for reviewers to look at the debdiff against what's in the archive.

Workflow

  • Candidates

    • Candidates get commented by reviewers as well as other contributors
    • Candidates get advocates when a reviewer is okay with it.
    • See Candidate life cycle

  • The last Candidate in a Candidate Series is the one that is available for review & commenting. The Series then has an overall approval status based on this last Candidate. The states are:

  • If a Candidate is for a source package which does not exist at all or is in closed state, then a new Candidate Series is created.
    • When a Candidate is first uploaded to revu & a Candidate Series is opened, the Series state is needs-review

  • A reviewer can look at a Candidate and can advocate or veto the Candidate.
    • If an Candidate Series refers to a package not in the (ubuntu) archive yet (NEW Package), it needs N advocates (currently 2) to enter "pending upload" state
  • Candidate Series referring to an existing package in the archive are considered to be updates. They need only 1 advocate to enter "pending upload" state.
  • If a reviewer advocates a Candidate, and that Candidate subsequently has enough advocations to be uploaded to the archive, then a message will show on the page to remind the reviewer to upload this Candidate when possible.
  • If a Candidate is reviewed and found to be flawed, then a reviewer can mark the Candidate as vetoed, and the Candidate Series state is set to needs-work
  • Once a Candidate is vetoed, only the removal of the veto by the reviewer, or a new Candidate will reset the state to needs-review
  • The appropriate *-changes lists for uploads into Ubuntu are monitored, and uploads of a Candidate to the archive close the Candidate Series.
  • If e.g. someone uploads a package with an equivalent change to the archive, which did not pass through revu, then the Candidate Series can be closed manually also.

Design

  • REVU2 has an apt-get source able repository (sources only!). This repository holds the latest Candidate of every Candidate Series.

  • REVU2 will authenticate against Launchpad
    • Contributors who upload packages for review would be part of the revu-uploaders Launchpad team. That team will be moderated by the ubuntu-dev team.

    • The ubuntu-dev team will be the reviewers

    • Ubuntu will ship a dput config ready to upload source packages to revu. The default will remain to upload to ubuntu.

REVU is implemented as Web application completely driven by an Web browser. To give most overview, there are different overview pages providing information to different needs.

User interface

The overview page of open uploads by a specific Contributors is the default page for users logged in presents a prioritized list of Candidate Series. The Candidate Series are sorted by the the following criteria:

  • open Candidate Series - states are based on the last Candidate in the Series
    • needs work
    • need reviews
    • pending Candidate Series
  • closed/done Candidate Series
    • The list of these will be sorted by date

This page is useful both for the contributor as well as for the TB for a quick overview about the contributions of an maintainer candidate.

Reviewers are likely to use the overview page for packages that need to be reviewed. Therefore this will be the first page reviewers see after they log in. This page presents a prioritized list of Candidate Series:

  • completely uncommented Candidates
  • Candidates with comments (no advocates yet)
  • Candidates with advocates (but are still in need reviewing state)
  • Candidates which have been vetoed (The reviewer who has vetoed can revoke his veto)
    • These need the veto removed or a new Candidate uploaded for the Series to progress back to needs-review state.

The overview of Candidates that are ready to be uploaded to the archive will also appear on the reviewers' page:

  • list all Candidates that need uploaded
    • (that is the last Candidate of an Candidate Series with enough Advocates)
  • download Candidate
    • provide prebuilt source package in separate directory for MOTUS to fetch, suitable for directly signing and uploading to the ubuntu archive

The overview pages mentioned above link to a package which provides a detailed view of the latest Candidate in a Candidate Series. This page present all (semi)automated reports as well as possible actions. Every user of REVU is able to comment on this Candidate. Reviewers get additional actions. They can:

  • request build. A build of this Candidate is triggered and a buildlog is generated. This report is added to this detail page as soon as the build finishes
  • veto, which cannot be overridden. This makes the Candidate Series to enter the "Needs Work" state.
  • advocating, which increases the count of advocates for this Candidate. previous votes do not count to new upload of Candidates into a Candidate Series
  • nuke a Candidate Series (for unredistributable/obvious broken/vetoed Candidate Series)
  • Request the package to be tested with piuparts and add that output to this detail page
  • mark as tested for a specific architecture (i386, amd64...)

Additionally to the possible actions, the overview pages presents various pieces of information about this upload. It should be easy to extend the list of presented information. The list includes:

  • lintian and linda report used in the latest available version
  • link to the package page in launchpad to easily look up the bugs in malone
  • link to the package page in debian, if the package exists there
  • link to the corresponding debbugs page
  • a dependency check to see if all (build)-dependencies are actually satisfiable, based on the current packages in the distribution that the Candidate is targeting.
  • a link to the copyright file in the source package
  • a link to rules file in the source package
  • a link showing the debdiff to the previous Candidate (if exists)
  • a link showing the debdiff to the latest version in ubuntu (if exists)
  • a link showing the debdiff to the latest version in debian (if exists)
    • This is useful for when changes are needed after upstream version freeze, and debian changes need to be merged.

The following list of pieces of information are only available after a successful build

  • list of files in the package
  • contents of the {post,pre}{inst,rm} scripts and the shlibs part of the binary package

Implementation

  • on tiber.tauware.de (canonical donated host, already up and running) we already have a prototype implementation. It was quite useful for learning which is really required to make Q/A adressed in this Spec most efficient. it is heavily using python.
    • REVU2 will continue to use python, and functionality will be separated between the backend which handles uploads, and performs package checking, and the frontend UI. This separation will be needed for a future migration to Launchpad.
    • REVU2 will probably only to be able to reuse a small amount of the prototype code. We want to wrap the code for the different overview pages in classes, so it can be easily adapted for use in e.g. launchpad in mind.
    • For this implementation, we will focus on the overview pages. This code is likley to be reused in a planned 3rd version of revu in launchpad itself (covered by another upcoming spec)
    • For security reasons, only reviewers are able to request builds of packages. Since revu currently operates on 1 publicly accessible machine, it is a large administrative overhead to provide adequate security for building packages automatically on upload. In the future, Launchpad will be used for building packages that are uploaded to it, but until then we will limit building to being triggered by reviewers.
    • We will use this ER Schema: ER

http://revu.tauware.de/cgi-bin/trac.cgi/file/trunk/doc/diagrams/ER.png

Outstanding issues

  • Bug elmo about enabling tiber to connect to the Launchpad AuthServer

BoF agenda and discussion


CategorySpec

REVU2Spec (last edited 2008-08-06 16:14:32 by localhost)