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