Documentation/topdocs/PATCHES.texi

   1 \input texinfo @c -*-texinfo-*-
   2 @setfilename PATCHES.info
   3 @settitle Toplevel
   4
   5 @node Top, , ,  (dir)
   6 @top
   7
   8 @unnumberedsec name
   9
  10
  11 PATCHES - track and distribute your code changes
  12
  13 @unnumberedsec description
  14
  15
  16 This page documents how to distribute your changes to GNU lilypond
  17
  18 @unnumberedsec abstract
  19
  20 We would like to have unified context diffs with full pathnames.  A
  21 script automating supplied with Lily.
  22
  23  Distributing a change normally
  24 goes like this:
  25
  26 @itemize @bullet
  27 @item make your fix/add your code
  28 @item Add changes to NEWS, and add yourself to Documentation/topdocs/AUTHORS.yo
  29 @item generate a patch,
  30 @item e-mail your patch to one of the mailing lists
  31     gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
  32 @end itemize
  33
  34 @unnumberedsec Generating a patch
  35
  36
  37 In @file{VERSION}, set MY_PATCH_LEVEL:
  38
  39 @example
  40
  41     VERSION:
  42         ...
  43         MY_PATCH_LEVEL=jcn1
  44
  45 @end example
  46
  47 In @file{CHANGES}, enter a summary of changes:
  48
  49 @example
  50         pl 0.1.73.jcn1
  51                 - added PATCHES.texi
  52 @end example
  53
  54 Then, from the top of Lily's source tree, type
  55
  56 @example
  57
  58     make dist
  59     make diff
  60
  61 @end example
  62
  63 which rolls the tarball @file{../releases/lilypond-0.1.73.tar.gz}
  64 and leaves your patch as @file{./lilypond-0.1.73.jcn1.diff}.
  65 @footnote{'Make diff' generates a patch between two tarballs.  For
  66 more info type 'make diff help=='.}  We assume that there is a tarball
  67 @file{lilypond-0.1.73.tar.gz} in the directory @file{../releases}.
  68
  69 If you didn't configure Lily using --srcdir, you can do:
  70
  71 @example
  72
  73     make release
  74
  75     tar-ball: ../patches/lilypond-0.1.73.jcn1.gz
  76     patch: ../patches/lilypond-0.1.73.jcn1.gz
  77 @end example
  78
  79 @unnumberedsec Prerequisites
  80
  81
  82 For creating a patch you need
  83
  84 @itemize @bullet
  85 @item All items mentioned in @file{INSTALL}.  You're not going to send a patch
  86     that you haven't even built, right?
  87 @item GNU diff
  88 @example
  89     make distclean
  90     cd ..
  91     diff -urN lilypond-0.1.73 lilypond-0.1.73.jcn1 > lilypond-0.1.73.jcn1
  92 @end example
  93
  94 but there are handy python scripts available.  If you're doing development,
  95 you'll need Python for other LilyPond scripts anyway.
  96
  97 @item The Lily directory structure, which looks like:
  98
  99     @example
 100
 101     doos/                        # gnu/windows32 build and binary releases
 102     harmonia -> harmonia-x.y.z
 103     harmonia-x.y.z/
 104     lilypond -> lilypond-x.y.z   # symlink to development directory
 105     lilypond-x.y.z/              # current development
 106     patches/                     # patches between different releases
 107     RedHat/BUILD                 # RedHat build and binary releases
 108     RedHat/RPMS
 109     RedHat/SPECS
 110     releases/                    # .tar.gz releases
 111     test/                        # tarballs and diffs from current version
 112     yodl -> yodl-1.30.17
 113     yodl-1.30.17
 114
 115 @end example
 116
 117 with prefix @file{$HOME/usr/src}
 118 and (for building rpms only) in @file{$HOME/.rpmrc}:
 119 @example
 120
 121     topdir: /home/fred/usr/src/RedHat
 122
 123 @end example
 124
 125 @end itemize
 126
 127 @unnumberedsec Applying patches
 128
 129
 130 If you're following LilyPond development regularly, you probably want to
 131 download just the patch for each subsequent release.
 132 After downloading the patch (into the patches directory, of course), simply
 133 apply it:
 134
 135 @example
 136
 137     gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
 138
 139 @end example
 140
 141 and don't forget to make automatically generated files:
 142
 143 @example
 144
 145     autoconf footnote(patches don't include automatically generated files,
 146     i.e. file(configure) and files generated by file(configure).)
 147
 148     configure
 149
 150 @end example
 151
 152 @unnumberedsec Synchronise
 153
 154
 155 If you're not very quick with sending your patch, there's a good
 156 chance that an new release of LilyPond comes available.  In such a
 157 case, the maintainer will probably ask you to make a new patch against
 158 the latest release.  Your best bet is to download the latest release,
 159 and apply your patch against this new source tree:
 160
 161 @example
 162
 163     cd lilypond-0.1.74
 164     gzip -dc ../patches/lilypond-0.1.73.jcn1.diff.gz | patch -p1 -E
 165     autoconf
 166     configure
 167
 168 @end example
 169
 170 Then, make a patch as shown above.
 171
 172 @unnumberedsec See also
 173
 174
 175 @file{stepmake/INSTALL.txt}
 176
 177 @unnumberedsec maintainer
 178
 179
 180 @email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}
 181
 182 Just keep on sending those patches!
 183
 184
 185 @bye