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