Changes between Initial Version and Version 1 of HgContributor


Ignore:
Timestamp:
10/23/2012 11:33:47 PM (2 years ago)
Author:
ltaylor.volks
Comment:

Initial instructions for contributors using Mercurial

Legend:

Unmodified
Added
Removed
Modified
  • HgContributor

    v1 v1  
     1= For Twisted contributors = 
     2 
     3If 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. 
     4 
     5There 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. 
     6 
     7== Using Mercurial Queues == 
     8Using the MQ extension allows you to work on an svn checkout and keep your changes versioned separate from the underlying repo.[[BR]] 
     9This is not a tutorial on the MQ extension, for that, see the [http://mercurial.selenic.com/wiki/MqExtension Mercurial documentation] 
     10 
     11 
     12=== Initial Setup === 
     131. Checkout Twisted trunk 
     14{{{ 
     15svn co svn://svn.twistedmatrix.com/svn/Twisted/trunk twisted-hg 
     16}}} 
     17 
     182. Enable the MQ extension in your .hgrc or Mercurial.ini 
     19{{{ 
     20[extensions] 
     21mq = 
     22}}} 
     23 
     243. Initialize the hg repo 
     25{{{ 
     26cd twisted-hg 
     27hg init 
     28}}} 
     29 
     303. Create an `.hgignore` file to prevent hg from adding temporary files, testing artifacts 
     31{{{ 
     32\.svn/ 
     33\.hgignore$ 
     34Twisted.egg-info/ 
     35dropin.cache 
     36_trial_temp 
     37\.o 
     38\.lo 
     39\.la 
     40\.py[co] 
     41build/ 
     42\.so$ 
     43\.orig 
     44\.rej 
     45}}} 
     46 
     474. Add files and create an initial commit to mark the SVN revision 
     48{{{ 
     49hg addremove 
     50hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`" 
     51}}} 
     52 
     53=== Work on your patch === 
     54The [http://mercurial.selenic.com/wiki/MqExtension MQ extension] provides a handy way to manage a queue of patches on top of the underlying repo. 
     55 
     56Create a new mercurial patch in the queue 
     57{{{ 
     58# Name the patch after the ticket# you are working on 
     59hg qnew -m "Working on new feature" feature-1234 
     60 
     61(hack hack hack) 
     62 
     63# Make sure the test suite passes 
     64trial twisted 
     65 
     66# Generate an svn diff to attach to the ticket 
     67svn diff > feature-1234.patch 
     68}}} 
     69 
     70=== Keeping up-to-date === 
     71Once 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 
     72{{{ 
     73# Pop all MQ patches off the queue. You're now back at the previous SVN checkout 
     74hg qrefresh 
     75hg qpop -a 
     76 
     77# Update the repo and sync a Mercurial commit 
     78svn up 
     79hg addremove -s 75 
     80hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`" 
     81 
     82# Re-apply your patch and deal with any conflicts using Mercurial's tools 
     83hg qpush feature-1234 
     84 
     85(hack hack hack) 
     86 
     87trial twisted 
     88 
     89# Generate a new svn diff to update the ticket 
     90svn diff > feature-1234-2.patch 
     91}}} 
     92 
     93 
     94== Improvements and Further Reading == 
     95 
     96'''Automation'''[[BR]] 
     97The synchronization steps above could be automated: 
     98{{{ 
     99hg qrefresh 
     100hg qpop -a 
     101svn up 
     102hg addremove -s 75 
     103hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`" 
     104}}} 
     105 
     106'''Patch queue versioning'''[[BR]] 
     107You may want to independently version your MQ patches, leaving your primary Mercurial repo commits dedicated solely to logging SVN updates: 
     108{{{ 
     109hg qinit -c 
     110hg commit --mq 
     111}}} 
     112 
     113=== hgsubversion === 
     114[https://bitbucket.org/durin42/hgsubversion/ hgsubversion] is a 3rd party tool dedicated to Subversion interoperability. 
     115 
     116Pending 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.