Documentation/topdocs/PATCHES.yo

   1 nsect(NAME)
   2
   3 PATCHES - track and distribute your code changes
   4
   5 nsect(DESCRIPTION)
   6
   7 This page documents how to distribute your changes to GNU lilypond
   8 (or in fact any other StepMake package).
   9
  10 nsect(ABSTRACT)
  11
  12 Distributing a change normally goes like this:
  13
  14 itemize(
  15 it()make your fix/add your code
  16 it()Add changes to NEWS, and add yourself to Documentation/AUTHORS.yo
  17 it()generate a patch,
  18 it()e-mail your patch to one of the mailing lists
  19     gnu-music-discuss@gnu.org or bug-gnu-music@gnu.org
  20 )
  21
  22 nsect(GENERATING A PATCH)
  23
  24 In file(VERSION), set MY_PATCH_LEVEL:
  25
  26 verb(
  27     VERSION:
  28         ...
  29         MY_PATCH_LEVEL=jcn1
  30 )
  31
  32 In file(NEWS), enter a summary of changes:
  33
  34 verb(
  35     NEWS:
  36         pl 0.1.73.jcn1
  37                 - added PATCHES.yo
  38 )
  39
  40 Then, from the top of Lily's source tree, type
  41
  42 verb(
  43     make diff
  44 )
  45
  46 which leaves your patch as file(./lilypond-0.1.73.jcn1.diff).
  47
  48 If you didn't configure Lily using --srcdir, you can do:
  49
  50 verb(
  51     make release
  52
  53     tar-ball: ../patches/lilypond-0.1.73.jcn1.gz
  54     patch: ../patches/lilypond-0.1.73.jcn1.gz
  55     updeet: ../test/updeet
  56 )
  57
  58 nsect(PREREQUISITES)
  59
  60 For creating a patch you need
  61
  62 itemize(
  63 it()All items mentioned in file(INSTALL).  You're not going to send a patch
  64     that you haven't even built, right?
  65 it()GNU diff
  66 it()Python (version 1.5 or newer).
  67     You can of course make a patch by hand, which would go something like:
  68
  69 verb(
  70     make distclean
  71     cd ..
  72     diff -urN lilypond-0.1.73 lilypond-0.1.73.jcn1 > lilypond-0.1.73.jcn1
  73 )
  74
  75 but there are handy python scripts available.  If you're doing development,
  76 you'll need Python for other LilyPond scripts anyway.
  77
  78 it()The Lily directory structure, which looks like:
  79
  80 includefile(../../stepmake/Documentation/layout.yo)
  81 )
  82
  83 nsect(APPLYING PATCHES)
  84
  85 If you're following LilyPond development regularly, you probably want to
  86 download just the patch for each subsequent release.
  87 After downloading the patch (into the patches directory, of course), simply
  88 apply it:
  89
  90 verb(
  91     gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
  92 )
  93
  94 and don't forget to make automatically generated files:
  95
  96 verb(
  97     autoconf footnote(patches don't include automatically generated files,
  98     i.e. file(configure) and files generated by file(configure).)
  99
 100     configure
 101 )
 102
 103 nsect(SYNCHRONISE)
 104
 105 If you're not very quick with sending your patch, there's a good chance
 106 that an new release of LilyPond comes available.  In such a case (and
 107 sometimes for other unkown reasons :-), the maintainer will probably ask
 108 you to make a new patch against the latest release.
 109 Your best bet is to download the latest release, and apply your patch
 110 against this new source tree:
 111
 112 verb(
 113     cd lilypond-0.1.74
 114     gzip -dc ../patches/lilypond-0.1.73.jcn1.diff.gz | patch -p1 -E
 115     autoconf
 116     configure
 117 )
 118
 119 Then, make a patch as shown above.
 120
 121 nsect(SEE ALSO)
 122
 123 file(stepmake/INSTALL.txt)
 124
 125 nsect(MAINTAINER)
 126
 127 nemail(Han-Wen Nienhuys)(hanwen@cs.uu.nl)
 128
 129 Just keep on sending those patches!
 130