Changes between Version 10 and Version 11 of WorkingConventions/Darcs


Ignore:
Timestamp:
Jun 21, 2014 3:20:48 PM (5 years ago)
Author:
thomie
Comment:

Obsolete

Legend:

Unmodified
Added
Removed
Modified
  • WorkingConventions/Darcs

    v10 v11  
    1 = Guidelines for using darcs with GHC =
    2 
    3 GHC uses [http://darcs.net/ darcs] for revision control.  This page describes various GHC-specific conventions for using darcs, together with some suggestions and tips for using darcs effectively.
    4 
    5 == General Guidelines ==
    6 
    7  * Try to make small patches (i.e. work in consistent increments).
    8 
    9  * Separate changes that affect functionality from those that just affect
    10    code layout, indendation, whitespace, filenames etc.  This means that
    11    when looking at patches later, we don't have to wade through loads of
    12    non-functional changes to get to the important parts of the patch.   
    13 
    14  * If possible, record often.  This helps to avoid conflicts.
    15 
    16  * Do not push conflicts, or submit patches with conflicts even if they are resolved (see [wiki:WorkingConventions/Darcs#Conflicts]).
    17 
    18  * Every patch must pass at least minimal validation: see TestingPatches.
    19 
    20  * Discuss anything you think might be controversial before pushing it.
    21 
    22 == Patch naming ==
    23 
    24 We have a simple naming convention for certain kinds of patches:
    25 
    26  * If your patch fixes breakage in the build, then begin the patch name with `"FIX BUILD"`. e.g.
    27 {{{
    28   FIX BUILD Use the right find on Windows systems; fixes bindist creation
    29 }}}
    30   The point here is that if someone pulls GHC from darcs and experiences a build failure, they can try
    31   `darcs pull -a -p "FIX BUILD"` in order to grab patches that fix it, without grabbing anything else
    32   that might introduce further breakage.
    33 
    34  * If your patch fixes a bug, then include the ticket number in the form `#NNNN` in the patch name, e.g.
    35 {{{
    36   FIX #767 (withMVar family have a bug)
    37 }}}
    38 
    39 == The stable branch ==
    40 
    41 The preferred way to make a change to the stable branch is to first record it on the HEAD,
    42 with a note in the commit message that it should be merged. You can then also push it to the
    43 stable branch if you wish, or you can leave it for the stable branch maintainer to do.
    44 
    45 Sometimes it is not possible to push the HEAD patch to the stable branch, as it may depend on
    46 other patches that are meant only for the HEAD. In this case the changes will need to be remade
    47 in the stable branch. The commit message for this new change should include the entire commit
    48 message of the original change, prefaced with `"MERGED: "`.
    49 The same patch should be pushed to both branches whenever possible, though, as it makes it
    50 easier to compare the two branches.
    51 
    52 If you first fix a problem in the stable branch then please do apply it only to that branch
    53 rather than leaving it lying around for when you have time to make the HEAD patch.
    54 
    55 == Conflicts ==
    56 
    57 Right now, we avoid having any conflicts in the GHC HEAD repository, because darcs currently doesn't handle conflicts well.  Don't push and conflicts, even resolved ones, to the GHC HEAD.  Instead amend-record or re-record your patches to fix the conflicts before pushing.
    58 
    59 Conflicts on branches are less of a problem, because branches usually have a limited life-span.  As long as the branch is not intended to be merged with the HEAD in the future (e.g. the stable branches), then small conflicts are ok.
    60 
    61 We're aware that this policy creates problems for development branches of GHC, and this is truly unfortunate.  We're hopeful that darcs' conflict handling will improve in the future and we can get the full power of darcs for separate development.
    62 
    63 == Committing changes ==
    64 
    65 If you have permission to push patches directly to the repository (pretty easy to get, just demonstrate your competence by sending us a patch or two first), then you can use {{{darcs push}}}:
    66 
    67 {{{
    68   $ darcs push <account>@darcs.haskell.org:/home/darcs/ghc
    69 }}}
    70 
    71 (change {{{ghc}}} to the name of the repository if you're pushing changes from one of the sub-repositories, like {{{testsuite}}}, or a package such as {{{base}}}.  Note: {{{darcs push}}} requires that SSH is working and can log in to your account on {{{darcs.haskell.org}}}.
    72 
    73 Do not forget to {{{darcs record}}} your changes first!
    74 
    75 == Pushing a whole tree ==
    76 
    77 A GHC tree consists of several repositories (see [wiki:Building/GettingTheSources]).  Sometimes you want to push from them all at the same time, for example after running a validate (see TestingPatches).
    78 
    79 It's good practice to have a completely clean set of repositories locally, i.e. a locally cached copy of the main repositories on `darcs.haskell.org`.  This is useful for creating new trees quickly, or comparing your trees to the HEAD.  To see which patches you have in a GHC tree relative to a clean repository, you can use the [wiki:Building/DarcsAll darcs-all script] in the root of the GHC repository:
    80 
    81 {{{
    82   $ ./darcs-all -r ~/ghc-HEAD push --dry-run --no-set-default
    83 }}}
    84 
    85 where `~/ghc-HEAD` is my vanilla HEAD, with all the sub-repositories checked out using `darcs-all`.  This command tells me all the patches in the local repository tree relative to `~/ghc-HEAD`.
    86 
    87 '''Tip''': add `pull --no-set-default` and `push --no-set-default` to your `~/.darcs/defaults` file, to avoid having to give `--no-set-default` in commands like the above.
    88 
    89 To actually push to the HEAD, you can do this:
    90 
    91 {{{
    92   $ ./darcs-all -r simonmar@darcs.haskell.org:/home/darcs push --no-set-default
    93 }}}
    94 
    95 it'll use SSH for the push, but continue to use HTTP for pulling, which is what you want (HTTP is much faster than SSH for darcs operations, but for pushing we can only use SSH).
    96 
     1This page is obsolete; please update links to point to [wiki:WorkingConventions/Git].