wiki:TwistedDevelopment

Version 55 (modified by rwall, 12 months ago) (diff)

Link to https://launchpad.net/divmod.org instead of https://launchpad.net/nevow (which seems to be dead)

Twisted Development

Contributing

Source Access

You can get Twisted's source code here:

svn://svn.twistedmatrix.com/svn/Twisted/trunk

What about Git/Bazaar/Mercurial?

Sure! If you prefer not to use svn, you can use a number of other version control systems to produce patches for review.

See DVCS Workflows for help using Git, Bazaar, and Mercurial to manage local development.

Submitting a Patch

Here's a quick step-by-step guide to getting from an idea for an improvement to Twisted to something that we can integrate. First, I'll explain just the mechanics of getting your code into review, not what the code itself should do. If you actually want us to be able to use your code, you will also want to read the section below on getting your patch accepted, too!

  1. Check out the source code, via the URL above, like this: svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk MyTwistedTrunk.
  2. Edit the code in the MyTwistedTrunk directory that you just checked out, making your awesome change to Twisted.
  3. Now is a good time to make sure that your patch fulfills all of the requirements of the review process, so you don't need to submit your patch many repeated times. Pay special attention to the section about news files!
  4. Generate a patch file by capturing the output of 'svn diff' at the root of your checkout - in this case, MyTwistedTrunk; the folder with "twisted", "bin", "doc", etc. in it. On Linux or MacOS, the command to create this file would be "cd MyTwistedTrunk; svn diff > my-twisted-patch.patch".
  5. If you haven't already, register for an account on this website. If you have, make sure you are logged in.
  6. Search for an existing ticket which describes your change, using both the "search" field above, and Google.
    1. If you can't find one, file a new ticket using the "new ticket" link above. If you file a new ticket, please start with a clear description of why such a change is desirable - we can read your code to find out what you are doing, but we can't read your mind to figure out why you want it done!
  7. Click on the "attach file" button on your ticket, and upload the .patch file you generated above.
  8. Put the ticket into review. This is accomplished by doing the following:
    1. enter the word "review" into the "keywords" field of the ticket. (If there are other keywords already there, just add a space to separate the keyword.)
    2. Click on the "reassign to" radio button.
    3. Select the topmost, blank entry from the "reassign to" button.
    4. Optionally, add a comment explaining which patch you would like reviewed (if there are already other attached files), and explaining what your change does (as opposed to the why you want it done, which you should have put into the ticket's summary and description).
    5. Hit "submit changes".
  9. At this point, you need to wait for feedback. If your patch is very good, very simple, and obviously correct, we may just apply it, but it is very unlikely that the first draft of a patch will be accepted as-is. When a Twisted developer reviews your patch, they will re-assign the ticket to you; you can see the list of tickets assigned to you by clicking here. Unfortunately, the time it takes us to deal with a ticket submitted for review is highly variable, and depends on how many other tickets are waiting review, the amount of free time that the Twisted core development team has, and how many resources we have available for sponsored development.
  10. When you do receive a review comment, attach a new patch (again un-assigning the ticket and adding the "review" keyword to it) which addresses that feedback.

Tools For Development

There are a few useful tools for developing Twisted. Some of them are included with Twisted, some are third-party dependencies.

To run the tests, simply run ./path/to/Twisted-checkout/bin/trial twisted.

To generate the narrative documentation, cd ./path/to/Twisted-checkout/doc; ../bin/lore/lore --config template=core/howto/template.tpl. (This should be simpler.) Then open index.html (not index.xhtml) in your web browser.

Many ancillary tools related to Twisted are in Bazaar repositories. You may find it useful to install the Bazaar version control system for your platform so that you can easily get access to these.

To generate the API documentation, you will need pydoctor. It depends on epydoc and nevow. Once you've got it, cd ./path/to/Twisted-checkout/; pydoctor --add-package twisted --make-html and look in the generated apidocs directory.

Getting Your Patch Accepted

If you are interested in contributing to Twisted for the first time, consider working on an existing ticket rather than contributing a new feature. Fixes for existing problems or implementations of already-requested features will generally take priority over new ideas. Consider discussing the work you want to do with other Twisted developers first.

Make sure that you have written unit tests and docstrings for all code which has changed in your patch. It works best if you use test-driven development to write your patch initially, and write your tests before your code. (Believe me, if you write your tests after you write your code, we will know. It's more obvious than you think.) See the Twisted Unit Tests standard for more on how to write and format your unit tests.

Run the full test suite ("trial twisted" on the command line) before submitting your patch, and fix any problems you discover. If a reviewer notices failing tests, they may not give your code a deep look, and you may have to wait longer for a second review.

(One minor caveat: some users may discover that their system is unusual and Twisted's test suite does not pass "out of the box". If this is the case, just make sure that the same tests are failing for you in a pristine checkout of trunk and with your changes applied. Then, in addition to submitting your patch, please let us know about the problem with the test suite!)

Our docstrings are formatted as Epytext.

Familiarize yourself with the Twisted coding standard, and make sure your contribution adheres to it.

Development Process

Twisted uses same process as Divmod: The Ultimate Quality Development System, in addition to this ReviewProcess. If you don't have commit access to Twisted, please submit changesets in diff -u format to the ticket tracker. To submit tickets, you must first register.

If you want to become a developer, it is important to understand that all your contributions (including those initial patches you send to the bug tracker) will have to be licenced under the MIT licence.

Filing Tickets

As The Ultimate Quality Development System mentions, all changes require a ticket. A Twisted ticket can be of one of three types.

  • Enhancements are used for feature additions. These typically take the form of a new API or an expansion of an existing API. Enhancement tickets should clearly describe the desired feature. The more well specified a feature is, the more likely it is to be implemented (and importantly, the more likely it is that what is implemented will actually be what the reporter wanted!) and the easier it is to implement. Remember that the ticket is possibly the only persistent record of the feature request. If it is not self-contained and sufficiently detailed, then it will likely fail to communicate the reporter's idea, diminishing its value (possibly all the way down to zero).
  • Defects are used to track bugs in existing APIs. Defect tickets are easier to specify than enhancements. A defect should briefly describe the problem, but the bulk of the ticket should be a runnable program (ideally in the form of a unit test) which demonstrates the bug.
  • Regressions are similar to defects, but are for bugs which are introduced into APIs in newer releases of Twisted. Like defect tickets, regression tickets should have a runnable program attached to demonstrate the problem.

Policies

This series of documents is designed for people who wish to contribute to the Twisted codebase.

Buildbot

After every commit to Twisted, the buildbot runs all the unit tests and reports test results on several platforms. Here is a page showing only the test results on supported platforms. All tests on supported platforms always pass. Watch the buildbot. Because sometimes, the buildbot watches back.

Win32 development

If you want to hack Twisted or just use Twisted SVN on Win32, see Ying Li's short tutorial on setting up a Twisted win32 development environment (and a small addendum on paths).

Twisted Maintenance

You might be interested in learning about tasks related to maintaining this website? or for releasing Twisted.

Links and Resources