|Version 29 (modified by exarkun, 6 years ago) (diff)|
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 accompanied by an entry in at least one topfiles directory (eg trunk/twisted/topfiles/ or trunk/twisted/names/topfiles/). This policy allows news files for releases to be generated automatically. See enforcenews.py for the svn pre-commit hook which enforces this policy. The entry must be a filed named <ticket number>.<change type>. The contents of the file must be a short (roughly one sentence) description of the change suitable for use in the release news file.<ticket number> is replaced by the ticket which is being resolved by the change (if multiple tickets are resolved, multiple files with the same contents should be added). <change type> is replaced by one of the following literal strings:
- feature - for tickets which are adding a new feature.
- bugfix - for tickets which are fixing a bug.
- removal - for tickets which are deprecating something or removing something which was already deprecated.
- misc - for tickets which are very minor and not worth summarizing outside of the svn changelog. These may be empty (their contents will be ignored).
- 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:
- Add review to the comma-separated keywords field
- 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.
- 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 bar.py to baz.py 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:
- Remove review from the comma-separated keywords field
- Change the owner back to the developer who put the ticket up for review
- 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?