Documentation/PATCHES.pod

   1 =head1 NAME
   2
   3 PATCHES - track and distribute your code changes
   4
   5 =head1 DESCRIPTION
   6
   7 This page documents how to distribute your changes to GNU LilyPond
   8
   9 =head1 ABSTRACT
  10
  11 Distributing a change normally goes like this:
  12
  13 =over 5
  14
  15 =item *
  16
  17 make your fix/add your code
  18
  19 =item *
  20
  21 generate a patch,
  22
  23 =item *
  24
  25 e-mail your patch to one of the mailing lists
  26 gnu-music-discuss@gnu.org or bug-gnu-music@gnu.org
  27 (or if you're a bit shy, to the maintainer).
  28
  29 =back
  30
  31 =head1 GENERATING A PATCH
  32
  33 In F<VERSION>, set TOPLEVEL_MY_PATCH_LEVEL:
  34
  35     VERSION:
  36         ...
  37         TOPLEVEL_MY_PATCH_LEVEL = jcn1
  38
  39 In F<NEWS>, enter a summary of changes:
  40
  41     NEWS:
  42         pl 0.1.48.jcn1
  43                 - added PATCHES.pod
  44
  45 Then, from the top of Lily's source tree, type
  46
  47     make distclean  # if you don't use --srcdir configure
  48     make-patch
  49
  50 which leaves your patch as F<./patch-0.1.48.jcn1>.
  51
  52 If you didn't configure Lily using --srcdir, you can do:
  53
  54     release
  55
  56     tar-ball: ../patches/patch-0.1.48.jcn1.gz
  57     patch: ../patches/patch-0.1.48.jcn1.gz
  58     updeet: ../test/updeet
  59
  60 =head1 PREREQUISITES
  61
  62 For creating a patch you need
  63
  64 =over 5
  65
  66 =item *
  67
  68 All items mentioned in F<INSTALL>.  You're not going to send a patch
  69 that you haven't even built, right?
  70
  71 =item *
  72
  73 GNU Diff
  74
  75 =item *
  76
  77 Python (version 1.4 or newer).
  78 You can of course make a patch by hand, which would go something like:
  79
  80     make distclean
  81     cd ..
  82     diff -urN lilypond-0.1.48 lilypond-0.1.48.jcn1 > patch-0.1.48.jcn1
  83
  84 but there are handy python scripts available.  If you're doing development,
  85 you'll need Python for other LilyPond scripts anyway.
  86
  87 =item *
  88
  89 The Lily directory structure, which looks like:
  90
  91     lilypond-0.1.48/
  92     patches/
  93     releases/
  94     test/
  95
  96 =back
  97
  98 =head1 SYNCHRONISE
  99
 100 If you're not very quick with sending your patch, there's a good chance
 101 that an new release of LilyPond comes available.  In such a case (and
 102 sometimes for other unkown reasons :-), the maintainer will probably ask
 103 you to make a new patch against the latest release.
 104 Your best bet is to download the latest release, and apply your patch
 105 against this new source tree:
 106
 107     cd lilypond-0.1.49
 108     zpatch -p0 -E < ../patches/patch-0.1.48.jcn1.gz
 109
 110 Then, make a patch as shown above.
 111
 112 =head1 MAINTAINER
 113
 114 Han-Wen Nienhuys <hanwen@cs.ruu.nl>
 115
 116 Just keep on sending those patches!
 117 =head1 NAME
 118
 119 PATCHES - track and distribute your code changes
 120
 121 =head1 DESCRIPTION
 122
 123 This page documents how to distribute your changes to GNU LilyPond
 124
 125 =head1 ABSTRACT
 126
 127 Distributing a change normally goes like this:
 128
 129 =over 5
 130
 131 =item *
 132
 133 make your fix/add your code
 134
 135 =item *
 136
 137 generate a patch,
 138
 139 =item *
 140
 141 e-mail your patch to one of the mailing lists
 142 gnu-music-discuss@gnu.org or bug-gnu-music@gnu.org
 143 (or if you're a bit shy, to the maintainer).
 144
 145 =back
 146
 147 =head1 GENERATING A PATCH
 148
 149 In F<VERSION>, set TOPLEVEL_MY_PATCH_LEVEL:
 150
 151     VERSION:
 152         ...
 153         TOPLEVEL_MY_PATCH_LEVEL = jcn1
 154
 155 In F<NEWS>, enter a summary of changes:
 156
 157     NEWS:
 158         pl 0.1.48.jcn1
 159                 - added PATCHES.pod
 160
 161 Then, type something like
 162
 163     make-dist
 164     mv out/lilypond-0.1.48.jcn1.tar.gz ../releases
 165     make-patch
 166
 167 which leaves your patch as F<./patch-0.1.48.jcn1>.
 168
 169 or even simpler:
 170
 171     release
 172
 173     tar-ball: ../patches/patch-0.1.48.jcn1.gz
 174     patch: ../patches/patch-0.1.48.jcn1.gz
 175     updeet: ../test/updeet
 176
 177 =head1 PREREQUISITES
 178
 179 For creating a patch you need
 180
 181 =over 5
 182
 183 =item *
 184
 185 All items mentioned in F<INSTALL>.  You're not going to send a patch
 186 that you haven't even built, right?
 187
 188 =item *
 189
 190 GNU Diff
 191
 192 =item *
 193
 194 Python (version 1.4 or newer).
 195 You can of course make a patch by hand, which would go something like:
 196
 197     make distclean
 198     cd ..
 199     diff -urN lilypond-0.1.48 lilypond-0.1.48.jcn1 > patch-0.1.48.jcn1
 200
 201 but there are handy python scripts available.  If you're doing development,
 202 you'll need Python for other LilyPond scripts anyway.
 203
 204 =item *
 205
 206 The Lily directory structure, which looks like:
 207
 208     lilypond-0.1.48/
 209     patches/
 210     releases/
 211     test/
 212
 213 =back
 214
 215 =head1 SYNCHRONISE
 216
 217 If you're not very quick with sending your patch, there's a good chance
 218 that an new release of LilyPond comes available.  In such a case (and
 219 sometimes for other unkown reasons :-), the maintainer will probably ask
 220 you to make a new patch against the latest release.
 221 Your best bet is to download the latest release, and apply your patch
 222 against this new source tree:
 223
 224     cd lilypond-0.1.49
 225     zpatch -p0 -E < ../patches/patch-0.1.48.jcn1.gz
 226
 227 Then, make a patch as shown above.
 228
 229 =head1 MAINTAINER
 230
 231 Han-Wen Nienhuys <hanwen@cs.ruu.nl>
 232
 233 Just keep on sending those patches!