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]