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