Changes between Version 13 and Version 14 of WorkingConventions/Git


Ignore:
Timestamp:
Aug 25, 2011 9:19:09 AM (3 years ago)
Author:
simonmar
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WorkingConventions/Git

    v13 v14  
     1[[PageOutline]] 
    12= Guidelines for using git with GHC = 
    23 
     
    4748Do this before you commit them! 
    4849 
    49 == Normal workflow == 
     50== Workflow with validate == 
    5051 
    51 Typical workflow for developing GHC is to have two trees, one called `ghc-working` and one called `ghc-validate`.  The idea is that you develop in the `ghc-working` tree, and when you're ready to push, [wiki:TestingPatches test the changes] in the `ghc-validate` tree before pushing up to the main GHC repo (or submitting patches, or sending a pull request). 
     52All changes to GHC and the libraries need to be [wiki:TestingPatches validated] before they can be pushed to the main repositories.  Validation can take a while - 30 minutes on a 4-core machine is typical - so ideally you want to be validating changes while you are working in a separate tree.  Furthermore, validation uses build settings that are different to the ones you would normally use while developing: it adds more libraries (DPH) and builds extra ways (dynamic libraries), so you don't want to use the same build for validation and ordinary development. 
     53 
     54So for this we normally use two entirely separate trees, one for developing and one for validating.  The development tree uses build settings optimised for development: `-O0 -DDEBUG` for the compiler, minimal libraries and ways so that rebuilding is fast.  The validate tree is for validating only. 
     55 
     56The typical workflow is to work in the development tree, pull into the validate tree, validate, and then push from the validate tree.  But what if validate fails?  There are two options: 
     57 
     58 1. discard the patch in the validate tree (using some instance of `git reset`) and go back to the working tree to fix it 
     59 2. or, add a new patch in the validate tree to fix the problem and re-validate 
     60 
     61(1) is more for "back to the drawing board" kinds of failure, whereas (2) is for cases where you just need to fix a warning or some other minor error exposed by validate. 
     62 
     63== Setting up the trees == 
     64 
     65Let's call the two trees `ghc-working` and `ghc-validate`. 
    5266 
    5367Set up your repos like this: 
     
    5670$ git clone http://darcs.haskell.org/ghc.git ghc-working 
    5771$ cd ghc-working 
    58 $ ./sync-all --testsuite get 
     72$ ./sync-all --testsuite --no-dph get 
    5973$ cd .. 
    6074$ git clone ghc-working ghc-validate 
     
    7084Now you have `ghc-working` and `ghc-validate` repos, and additionally the `ghc-validate` repo tree is set up with a remote `working` pointing to the `ghc-working` tree, and pushing from `ghc-validate` will push changes via SSH to `darcs.haskell.org`. 
    7185 
    72 To pull from working into the `ghc-validate` tree: 
     86== The rebase workflow == 
     87 
     88How do we move patches from `ghc-working` and `ghc-validate`?  There are several options here.  One is to just use `sync-all pull working` and do merging as usual.  This works fine, but results in extra "merge commits" that aren't particularly helpful and clutter the commit logs and the mailing list.  A better approach is to rebase patches before committing.  This is done as follows: 
     89 
     90  1. fetch patches from `ghc-working` into `ghc-validate`: `./sync-all fetch working` 
     91  2. merge from working: `./sync-all merge working` 
     92  3. rebase onto master: `./sync-all pull --rebase` 
     93  4. validate, push 
     94 
     95Now, the patches pushed this way are different (have different hashes) from the patches that you originally committed in `ghc-working`, and if you try to pull these patches in `ghc-working` again, confusion and conflicts will ensue.  Fortunately there's an easy solution: just rebase again in `ghc-working`, and git will notice that your patches are already upstream and will discard the old versions.  It's as simple as 
    7396 
    7497{{{ 
    75 cd ghc-validate 
    76 ./sync-all fetch working 
     98 $ cd ghc-working 
     99 $ ./sync-all pull --rebase 
    77100}}} 
    78101 
    79 Then merge changes from `working` into the `master` branch of `ghc-validate` as appropriate.  Then: 
     102If rebase encounters a conflict at any point, it will tell you what to do.  After fixing the conflict and completing the rebase manually, you can then resume the pull with `./sync-all --resume pull --rebase`. 
    80103 
    81 {{{ 
    82 ./sync-all pull 
    83 }}} 
    84  
    85 To get changes from upstream, merging if necessary.  At this point you can check what changes are new in your tree relative to upstream: 
    86  
    87 {{{ 
    88 ./sync-all new 
    89 }}} 
    90  
    91 Then run `sh validate`, and if all is well: 
    92  
    93 {{{ 
    94 ./sync-all push 
    95 }}} 
    96  
    97 to push. 
    98104 
    99105== Contributing patches ==