Changes between Initial Version and Version 1 of HgContributor

10/23/2012 11:33:47 PM (3 years ago)

Initial instructions for contributors using Mercurial


  • HgContributor

    v1 v1  
     1= For Twisted contributors = 
     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. 
     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. 
     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 [ Mercurial documentation] 
     12=== Initial Setup === 
     131. Checkout Twisted trunk 
     15svn co svn:// twisted-hg 
     182. Enable the MQ extension in your .hgrc or Mercurial.ini 
     21mq = 
     243. Initialize the hg repo 
     26cd twisted-hg 
     27hg init 
     303. Create an `.hgignore` file to prevent hg from adding temporary files, testing artifacts 
     474. Add files and create an initial commit to mark the SVN revision 
     49hg addremove 
     50hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`" 
     53=== Work on your patch === 
     54The [ MQ extension] provides a handy way to manage a queue of patches on top of the underlying repo. 
     56Create a new mercurial patch in the queue 
     58# Name the patch after the ticket# you are working on 
     59hg qnew -m "Working on new feature" feature-1234 
     61(hack hack hack) 
     63# Make sure the test suite passes 
     64trial twisted 
     66# Generate an svn diff to attach to the ticket 
     67svn diff > feature-1234.patch 
     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 
     73# Pop all MQ patches off the queue. You're now back at the previous SVN checkout 
     74hg qrefresh 
     75hg qpop -a 
     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`" 
     82# Re-apply your patch and deal with any conflicts using Mercurial's tools 
     83hg qpush feature-1234 
     85(hack hack hack) 
     87trial twisted 
     89# Generate a new svn diff to update the ticket 
     90svn diff > feature-1234-2.patch 
     94== Improvements and Further Reading == 
     97The synchronization steps above could be automated: 
     99hg qrefresh 
     100hg qpop -a 
     101svn up 
     102hg addremove -s 75 
     103hg checkin -m "sync SVN @ `svn info | grep Revision | cut d ' ' -f 2`" 
     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: 
     109hg qinit -c 
     110hg commit --mq 
     113=== hgsubversion === 
     114[ hgsubversion] is a 3rd party tool dedicated to Subversion interoperability. 
     116Pending resolution of this [ issue], it's likely that hgsubversion could be used to allow for a more natural workflow.