Changes between Version 14 and Version 15 of WorkingConventions/Repositories


Ignore:
Timestamp:
Dec 19, 2012 3:04:14 PM (3 years ago)
Author:
simonpj
Comment:

--

Legend:

Unmodified
Added
Removed
Modified
  • WorkingConventions/Repositories

    v14 v15  
    1  
    2 = GHC libraries and other packages = 
    3  
    4 As well as the GHC repository itself, there are a number libraries 
    5 and other packages that make up a GHC tree. This page describes the 
    6 process by which those libraries can be altered. 
    7  
    8 See the [wiki:Repositories] page for the context. 
    9  
    10 == Packages for which we use the upstream repository directly == 
    11  
    12 In the case of 
    13  
    14  * utils/hsc2hs 
    15  * utils/haddock 
    16  * libraries/array 
    17  * libraries/base 
    18  * libraries/deepseq 
    19  * libraries/directory 
    20  * libraries/filepath 
    21  * libraries/ghc-prim 
    22  * libraries/haskell98 
    23  * libraries/haskell2010 
    24  * libraries/hoopl 
    25  * libraries/hpc 
    26  * libraries/integer-gmp 
    27  * libraries/integer-simple 
    28  * libraries/old-locale 
    29  * libraries/old-time 
    30  * libraries/process 
    31  * libraries/template-haskell 
    32  * libraries/unix 
    33  * libraries/dph 
    34  * libraries/parallel 
    35  * libraries/stm 
    36  
    37 we use the main repository directly. Therefore changes can be pushed 
    38 directly, as with GHC patches. 
    39  
    40 When making a change to a library, you must also update the version 
    41 number if appropriate. Version number in the repositories should be 
    42 maintained such that, if the library were to be release as-is, then 
    43 they would have the correct version number. For example, if the last 
    44 release of a library was 1.2.0.3 and you remove a function from it 
    45 then, as per the 
    46 [http://www.haskell.org/haskellwiki/Package_versioning_policy Package versioning policy], 
    47 the version number should be bumped to 1.3.0.0. If it is already 
    48 1.3.0.0 or higher then no further change is necessary. In order to 
    49 make this easier, the version line in the `.cabal` file should be 
    50 followed by a comment such as 
    51 {{{ 
    52 -- GHC 7.6.1 released with 1.2.0.3 
    53 }}} 
    54  
    55 == Packages for which there is a separate upstream repository == 
    56  
    57 In the case of 
    58  
    59  * libraries/binary 
    60  * libraries/bytestring 
    61  * libraries/Cabal 
    62  * libraries/containers 
    63  * libraries/haskeline 
    64  * libraries/pretty 
    65  * libraries/terminfo 
    66  * libraries/time 
    67  * libraries/transformers 
    68  * libraries/xhtml 
    69  * libraries/Win32 
    70  * libraries/primitive 
    71  * libraries/vector 
    72  
    73 there is a separate upstream repository. 
    74  
    75 The process for updating these is a little more complicated, motivated 
    76 by the following objectives: 
    77  
    78  1. Any changes needed by GHC should be made not only in our repository, 
    79     but also in the upstream repository. 
    80  
    81  2. Being used in a GHC tree should not make life harder for the 
    82     upstream maintainer. 
    83  
    84 Note that these two objectives are to some extent in conflict: If a 
    85 change in GHC or one of its libraries requires a change in a library 
    86 with an upstream repo then, in order to satisfy objective 1, the 
    87 maintainer would need to apply the patch, but if doing so is currently 
    88 inconvenient for them then this would fail objective 2. This policy 
    89 therefore tries to find the best compromise, without being too onerous 
    90 for any party. 
    91  
    92 For these repositories, we use a "git submodule" rather than a normal 
    93 repository. Using submodules means that the repository doesn't need to 
    94 follow a linear path through the git history, but can instead jump 
    95 around, for example from a release commit on one branch to the next 
    96 release commit on a different branch. 
    97  
    98 === From the GHC developer's point of view === 
    99  
    100 If you are not modifying these packages then you don't need to do 
    101 anything special: A regular `./sync-all pull` will update the submodules 
    102 as normal. However, you may find it useful to run 
    103 {{{ 
    104 git config --global diff.ignoreSubmodules dirty 
    105 }}} 
    106 or each time you run `git status` or `git diff`, git will check for 
    107 changes not only in the GHC repository, but also in all the submodules. 
    108 (you must have `git >= 1.7.3` for this to work). 
    109  
    110 If you need to modify one of these libraries, then ordinarily you should 
    111 first send the modifications upstream. Ideally upstream will apply the 
    112 patches and make a release (the easiest way to acomplish objective 1 is 
    113 for changes to be applied upstream ''first'', so that they can't be 
    114 forgotten about after being applied to GHC's repo). You can then update 
    115 GHC's submodule by running 
    116 {{{ 
    117 cd libraries/foo 
    118 git reset --hard some_commit_id 
    119 cd ../.. 
    120 git commit -a 
    121 ./sync-all push 
    122 }}} 
    123  
    124 There are some scenarios where you may need to modify GHC's repository 
    125 without the upstream repository already having the change that you need: 
    126  
    127  * The maintainer may tell you that they are too busy to deal with the 
    128    package at the moment, or not be responding at all. In this case, it 
    129    may be necessary to make changes only to GHC's repositories in the 
    130    short term, and for the changes to be merged upstream later. 
    131  
    132  * In a GHC stable branch, we may be using an old version of a library 
    133    that we need to make a change to, but upstream may only be interested 
    134    in working on the latest version rather than also maintaining old 
    135    release branches. In that case, we would only make the change in the 
    136    GHC respository. 
    137  
    138 In order to make the change in this case, you 
    139 {{{ 
    140 cd libraries/foo 
    141 git commit -a 
    142 cd ../.. 
    143 git commit -a 
    144 ./sync-all push 
    145 }}} 
    146  
    147 '''Important:''' If you make a change to a submodule, then make sure you 
    148 commit in both that repository and the ghc repository before using 
    149 `./sync-all get` or `./sync-all pull`. Those commands run 
    150 `git submodule update`, which may cause you to lose unrecorded changes. 
    151  
    152 === From the upstream maintainer's point of view === 
    153  
    154 Upstream maintainers don't need to do anything special. You can continue 
    155 to use any version control system and whatever branching policy works best 
    156 for you. However, there are two issues to be aware of: 
    157  
    158  * For libraries that are shipped with GHC, we need to have releases of 
    159    libraries that can build with that GHC. There may be no suitable 
    160    existing release (most commonly due to trivial things such as library 
    161    dependencies needing to be changed, but sometimes due to real changes 
    162    in other libraries or the compiler), in which case we will request 
    163    that you make a suitable release or, if it is not convenient for you 
    164    to do so, we can make one on your behalf (in which case it will 
    165    normally have only the minimal changes necessary since the previous 
    166    release). 
    167  
    168  * Sometimes we may need to make changes to old versions of libraries, 
    169    as we try to avoid making interface changes within GHC stable 
    170    branches and upstream development may have moved on since a GHC 
    171    stable branch was created. When this happens it is up to you whether 
    172    the changes are sent upstream as normal (and maintained in an upstream 
    173    branch), or whether they are left only in the GHC repository. Note that 
    174    if they are made only the GHC repository then we will probably need to 
    175    make a release from the GHC repository, as per the previous point. 
     1This page has been replace by  
     2 * [wiki:Repositories] 
     3 * [wkik:Repositories/Upstream]