= For Twisted contributors =

If you want to develop a patch for Twisted (as described in the BasicGuideToContributingCode) but prefer to use Mercurial rather than SVN, this is the section for you.

There are no official Mercurial mirrors at this time; however, since creating a new patch doesn't require the complete repo history, one recommended workflow is to use Mercurial Queues.

== Using Mercurial Queues ==
Using the MQ extension allows you to work on an svn checkout and keep your changes versioned separate from the underlying repo.[[BR]]
This is not a tutorial on the MQ extension, for that, see the [http://mercurial.selenic.com/wiki/MqExtension Mercurial documentation]


=== Initial Setup ===
1. Checkout Twisted trunk
{{{
svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk twisted-hg
}}}

2. Enable the MQ extension in your .hgrc or Mercurial.ini
{{{
[extensions]
mq =
}}}

3. Initialize the hg repo
{{{
cd twisted-hg
hg init
}}}

3. Create an `.hgignore` file to prevent hg from adding temporary files, testing artifacts
{{{
\.svn/
\.hgignore$
Twisted.egg-info/
dropin.cache
_trial_temp
\.o
\.lo
\.la
\.py[co]
build/
\.so$
\.orig
\.rej
}}}

4. Add files and create an initial commit to mark the SVN revision
{{{
hg addremove
hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`"
}}}

=== Work on your patch ===
The [http://mercurial.selenic.com/wiki/MqExtension MQ extension] provides a handy way to manage a queue of patches on top of the underlying repo.

Create a new mercurial patch in the queue
{{{
# Name the patch after the ticket# you are working on
hg qnew -m "Working on new feature" feature-1234

(hack hack hack)

# Make sure the test suite passes
trial twisted

# Generate an svn diff to attach to the ticket
svn diff > feature-1234.patch
}}}

=== Keeping up-to-date ===
Once you've submitted your patch for review, it may take some time before you get feedback. You'll want to synchronize with SVN and make sure your patch applies cleanly or deal with any conflicts
{{{
# Pop all MQ patches off the queue. You're now back at the previous SVN checkout
hg qrefresh
hg qpop -a

# Update the repo and sync a Mercurial commit
svn up
hg addremove -s 75
hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`"

# Re-apply your patch and deal with any conflicts using Mercurial's tools
hg qpush feature-1234

(hack hack hack)

trial twisted

# Generate a new svn diff to update the ticket
svn diff > feature-1234-2.patch
}}}


== Improvements and Further Reading ==

'''Automation'''[[BR]]
The synchronization steps above could be automated:
{{{
hg qrefresh
hg qpop -a
svn up
hg addremove -s 75
hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`"
}}}

'''Patch queue versioning'''[[BR]]
You may want to independently version your MQ patches, leaving your primary Mercurial repo commits dedicated solely to logging SVN updates:
{{{
hg qinit -c
hg commit --mq
}}}

=== hgsubversion ===
[https://bitbucket.org/durin42/hgsubversion/ hgsubversion] is a 3rd party tool dedicated to Subversion interoperability.

Pending resolution of this [https://bitbucket.org/durin42/hgsubversion/issue/350/hgsubversion-hangs-on-specific-revision-in issue], it's likely that hgsubversion could be used to allow for a more natural workflow.