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 dist
  44     make diff
  45 )
  46
  47 which rolls the tarball file(../releases/lilypond-0.1.73.tar.gz)
  48 and leaves your patch as file(./lilypond-0.1.73.jcn1.diff).
  49 footnote('Make diff' generates a patch between two tarballs.  For
  50 more info type 'make diff help=='.  We assume that there is a tarball
  51 file(lilypond-0.1.73.tar.gz) in the directory file(../releases).
  52
  53
  54 If you didn't configure Lily using --srcdir, you can do:
  55
  56 verb(
  57     make release
  58
  59     tar-ball: ../patches/lilypond-0.1.73.jcn1.gz
  60     patch: ../patches/lilypond-0.1.73.jcn1.gz
  61     updeet: ../test/updeet
  62 )
  63
  64 nsect(PREREQUISITES)
  65
  66 For creating a patch you need
  67
  68 itemize(
  69 it()All items mentioned in file(INSTALL).  You're not going to send a patch
  70     that you haven't even built, right?
  71 it()GNU diff
  72 it()Python (version 1.5 or newer).
  73     You can of course make a patch by hand, which would go something like:
  74
  75 verb(
  76     make distclean
  77     cd ..
  78     diff -urN lilypond-0.1.73 lilypond-0.1.73.jcn1 > lilypond-0.1.73.jcn1
  79 )
  80
  81 but there are handy python scripts available.  If you're doing development,
  82 you'll need Python for other LilyPond scripts anyway.
  83
  84 it()The Lily directory structure, which looks like:
  85
  86 includefile(../../stepmake/Documentation/layout.yo)
  87 )
  88
  89 nsect(APPLYING PATCHES)
  90
  91 If you're following LilyPond development regularly, you probably want to
  92 download just the patch for each subsequent release.
  93 After downloading the patch (into the patches directory, of course), simply
  94 apply it:
  95
  96 verb(
  97     gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
  98 )
  99
 100 and don't forget to make automatically generated files:
 101
 102 verb(
 103     autoconf footnote(patches don't include automatically generated files,
 104     i.e. file(configure) and files generated by file(configure).)
 105
 106     configure
 107 )
 108
 109 nsect(SYNCHRONISE)
 110
 111 If you're not very quick with sending your patch, there's a good chance
 112 that an new release of LilyPond comes available.  In such a case (and
 113 sometimes for other unkown reasons :-), the maintainer will probably ask
 114 you to make a new patch against the latest release.
 115 Your best bet is to download the latest release, and apply your patch
 116 against this new source tree:
 117
 118 verb(
 119     cd lilypond-0.1.74
 120     gzip -dc ../patches/lilypond-0.1.73.jcn1.diff.gz | patch -p1 -E
 121     autoconf
 122     configure
 123 )
 124
 125 Then, make a patch as shown above.
 126
 127 nsect(SEE ALSO)
 128
 129 file(stepmake/INSTALL.txt)
 130
 131 nsect(MAINTAINER)
 132
 133 nemail(Han-Wen Nienhuys)(hanwen@cs.uu.nl)
 134
 135 Just keep on sending those patches!
 136