Version 23 (modified by thijs, 6 years ago)

use trac source links

Twisted Code Review Process

The post-development, pre-commit process Twisted has adopted is this:

  • Commits to trunk/ must be the result of the review process outlined below. The only exception to this is the Twisted.Quotes file. There are no other exceptions.

  • Changes to Twisted must be accompanied by a ticket in the tracker.

  • Changes must be reviewed by a developer other than the author of the changes. If changes are paired on, a third party must review them. If changes constitute the work of several people who worked independently, a non-author must review them.

  • When a ticket becomes ready for review, the trac workflow for the developer is as follows:
    1. Add review to the comma-separated keywords field
    2. Change the owner to either no one or, if a particular developer is likely to review a branch or a particular developer's input is desired on the branch, that developer. For the former case, when starting a review the reviewer should assign the ticket to themselves.
    3. Comment on the ticket indicating anything it might be beneficial for the reviewer to know. Tickets should be described well enough that the change is already justified and the new code should be easy enough to read that further explanations aren't necessary to understand it, but sometimes diffs themselves can be more difficult to read than either the old or new state of the code, so comments like the implementation of foo moved from to can sometimes make a reviewer's job easier.
  • A reviewer can be anyone who is familiar with the Twisted codebase, coding standard, and review requirements. A reviewer need not necessarily be familiar with the specific area of Twisted being changed, but he or she should feel confident in his or her abilities to spot problems in the change.

  • A reviewer must reject a set of changes which doesn't meet all of the following conditions:
    • The test suite passes on all of the supported* platforms with the changes.
    • The changes must have tests for any alterations of behavior.
    • The changes must have test coverage for all new behavior.
    • The changes must have full documentation for new public APIs and test methods.
    • The changes must add docstrings for any modifed public APIs or test methods which were previously undocumented (ie, if a function which has no docstring was modified, or a class which has no docstring had methods added to it).
    • The changes must include updates to the documentation for any modified behavior of an API.
    • If appropriate, the changes must include "user guide" documentation in the doc/ directory.
    • The changes must include updated documentation for any APIs which are being deprecated or otherwise obsoleted.
    • The changes must follow the coding standard.
    • The changes must not be obviously buggy: pyflakes is an useful tool to check basic quality of code. The following command will check all the files modified and added by a branch merge:
      svn status | grep '^\M\|^A' | cut -c 8- | xargs pyflakes
  • A reviewer may reject a set of changes for other reasons, most of which are hard to quantify. Basically, use your best judgement, and don't be afraid to point out problems which don't fit into the above list.
  • When a reviewer has completed a review, the trac workflow is as follows:
    1. Remove review from the comma-separated keywords field
    2. Change the owner back to the developer who put the ticket up for review
    3. Put whatever review comments are being offered into a comment on the ticket

  • After a reviewer has given a change set the okay, the author (or another developer, if the author is so inclined or lacks commit privileges) may commit the change set to trunk.

  • The trunk commit must include the name of the author or authors, reviewer or reviewers, and the tickets which are being resolved by the changes being committed. The suggested format for this is:
    Merge <branch name>: Brief description
    Long description (as long as you wish)
    Author: <names> Reviewer: <names> Fixes: #<ticket number>

Several tools exist which parse commit messages to trunk, so the Author, Reviewer, and Fixes lines should conform to this format exactly. Multiple Fixes lines will close multiple tickets. Refs may also be used to attach the commit message to another ticket which is not being closed. The commit message should also describe the change being made in a modest amount of detail. This should be detailed enough for someone doing a release to formulate a changelog entry.

  • If a change set somehow introduces a test suite regression or is otherwise found to be undesirable, it is to be reverted. Any developer may revert a commit which introduces a test suite regression on a supported platform. The revert message should be as explicit as possible. If it's a failure, put the message of the error in the commit message, possibly with the identifier of the buildbot slave. If there are too many failures, it can be put in the tracker, with a reference in the message. Use the "Reopens" tag to automatically reopen the ticket:
    Revert r<revision number>: Brief description
    A description of the problem, or a traceback if pertinent
    Reopens #<ticket number>
  • Reverted branches are to be reviewed again before being merged.

  • If a branch is used, it should be deleted a short time after after it is merged into trunk (leaving enough time for the buildslaves to run to completion is a good idea, in case a regression has been introduced and the merge must be reverted).

Some of the higher level things for a reviewer to consider about a branch:

  • Does it change existing APIs in an incompatible way? Are these APIs stable enough to warrant backwards compatibility or a deprecation period?
  • Is the code written in a straightforward manner which will allow it to be easily maintained in the future, possibly by a developer other than the author?
  • If it introduces a new feature, is that feature generally useful and have its long term implications been considered and accounted for?
    • Will it result in confusion to application developers?
    • Does it encourage application code using it to be well factored and easily testable?
    • Is it similar to any existing feature offered by Twisted, such that it might make sense as an extension or modification to some other piece of code, rather than an entirely new functional unit?