wiki:TwistedWithCombinator

Version 15 (modified by thijs, 16 months ago) (diff)

fix typo

A brief guide to the basic Combinator functions used in Twisted development.

(Throughout the instructions on this page, replace ashfall with the username with which your svn account was created)

  • Get your commit rights. Head to #twisted, bug a core developer till he/she creates an svn account for you. You will need to provide your SSH key. If it's on launchpad (it's good to have it on launchpad - here's help), you can just point them there.
  • You should now be able to ssh to
    ashfall@svn.twistedmatrix.com
    
    (Note that this is just a one time check, in general, you won't log in to svn.twistedmatrix.com anymore, and you should use your usual local shell from here.)
  • Make sure you follow this checklist while committing to trunk.

Setup

  • Have a directory where your svn checkouts will be. For example, ~/MyProjects/.
  • Get Combinator from launchpad and put it into a directory it can recognize:
    cd ~/MyProjects; mkdir Divmod; bzr branch lp:divmod.org Divmod/trunk
    
  • Enter this in a shell (or put it in a startup file):
    eval `python path/to/Divmod/trunk/Combinator/environment.py`
    
  • To get started, check out a read-write version of Twisted trunk and add it to your Python import path:
    chbranch Twisted trunk svn+ssh://ashfall@svn.twistedmatrix.com/svn/Twisted/trunk
    
    • Now if you import Twisted in that shell, you should get the new checkout:
      python -c 'from twisted import __file__; print __file__'
      

Basic Commands

chbranch

chbranch is the tool for switching to a different branch. Provide chbranch with a project name and branch name and it will modify all Combinator-enabled environments so that Python imports are satisfied from that branch of the project. If necessary, the branch will be checked out.

mkbranch

mkbranch is the tool for creating new branches. Provide mkbranch with a project name and branch name and it will create a new branch with that name, switch a copy of trunk to it, and do the equivalent of a chbranch to the new branch.

Note: make sure to remove the _trial_temp folder, a temporary folder created when running the Twisted unit tests, before running this command.

unbranch

unbranch is the tool for merging a branch's changes into trunk. First, use chbranch to change to the branch to be merged. Then, make sure that the trunk working copy either contains no changes or contains only changes which you want included in the merge (note: it is strongly, strongly recommended that if the merge will be committed that the trunk working copy contain no changes). Finally, run unbranch with the project name and the changes from the branch will be merged into the trunk working copy. They will not be committed automatically.

Making a new branch:

  • Use mkbranch:
    mkbranch Twisted <your-branch-name>-<ticket number>
    
    • Twisted uses a particular convention for branch names to help with trac integration: <descriptive words about the purpose of the branch>-<ticket number>. For example, stdio-endpoint-plugin-5729.
    • The ticket number in the branch name is how the "Branch:" field in trac gets populated.
    • Make sure to remove the _trial_temp folder, a temporary folder created when running the Twisted unit tests, before running this command.
  • mkbranch creates the branch on the svn server and gives you a checkout of it in ~/MyProjects/Twisted/branches/. So once you've made it, you can work on the checkout there, commit whatever changes you want, and then eventually submit it for review.

Note:

  • Combinator might give you some trouble if you have unmerged changes in your local copy of trunk (i.e. .../Twisted/trunk), so make sure you clean everything after merging forward or resolving conflicts:
    cd trunk; svn revert . -R; svn st | xargs rm -r; svn up
    

To Merge a Branch

  1. Check if you are on the branch which you want to merge:
    whbranch Twisted
    
    If not, do:
    chbranch Twisted <branch-name>
    
  1. Unbranch:
    unbranch Twisted
    
  1. Go to trunk and commit:
    cd trunk;
    svn commit -m '<message';
    
    Please note that the commit message must be of the format mentioned here.

Merging Forward

Merging forward is a way to keep old branches fresh and up-to-date.

Before you merge forward, make sure your trunk working copy is clean and all your existing branch changes are checked in. Follow steps 1 through 2 from instructions to merge a branch, and then:

  1. Resolve conflicts, if any. Then run the following for every conflicted file you resolved:
    svn resolved <previously-conflicted-file>
    
  1. Make a new branch (merge-forward):
    mkbranch Twisted <old-branch-name>-2
    
    Please increment '2' above, as appropriate, looking at the branch no. in <old-branch-name>.
  1. Commit the new branch
    cd <old-branch-name>-2
    svn commit -m <message about merging forward and resolving conflicts>
    
  1. Delete the old branch

  1. Make sure you revert trunk working copy:
    cd trunk; svn revert . -R; svn st | xargs rm -r; svn up
    

The archive of Divmod Combinator tutorial talks a bit more about how this works, you can take a look if you want to read more.

See Also