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 SYNCHRONISE
  98
  99 If you're not very quick with sending your patch, there's a good chance
 100 that an new release of LilyPond comes available.  In such a case (and
 101 sometimes for other unkown reasons :-), the maintainer will probably ask
 102 you to make a new patch against the latest release.
 103 Your best bet is to download the latest release, and apply your patch
 104 against this new source tree:
 105
 106     cd lilypond-0.1.49
 107     zpatch -p0 -E < ../patches/patch-0.1.48.jcn1.gz
 108
 109 Then, make a patch as shown above.
 110
 111 =head1 MAINTAINER
 112
 113 Han-Wen Nienhuys <hanwen@cs.ruu.nl>
 114
 115 Just keep on sending those patches!