\input texinfo @c -*-texinfo-*-
@setfilename PATCHES.info
@settitle Toplevel

@node Top, , ,  (dir)
@top

@unnumberedsec name
    

PATCHES - track and distribute your code changes

@unnumberedsec description
    

This page documents how to distribute your changes to GNU lilypond

@unnumberedsec abstract
    
We would like to have unified context diffs with full pathnames.  A
script automating supplied with Lily.

 Distributing a change normally
goes like this:

@itemize @bullet
@item make your fix/add your code 
@item Add changes to NEWS, and add yourself to Documentation/topdocs/AUTHORS.yo
@item generate a patch, 
@item e-mail your patch to one of the mailing lists
    gnu-music-discuss@@gnu.org or bug-gnu-music@@gnu.org
@end itemize

@unnumberedsec Generating a patch
    

In @file{VERSION}, set MY_PATCH_LEVEL:

@example 

    VERSION:
	...
	MY_PATCH_LEVEL=jcn1
 
@end example 

In @file{CHANGES}, enter a summary of changes:

@example 
	pl 0.1.73.jcn1
		- added PATCHES.texi
@end example 

Then, from the top of Lily's source tree, type

@example 

    make dist
    make diff
 
@end example 

which rolls the tarball @file{../releases/lilypond-0.1.73.tar.gz}
and leaves your patch as @file{./lilypond-0.1.73.jcn1.diff}.
@footnote{'Make diff' generates a patch between two tarballs.  For 
more info type 'make diff help=='.}  We assume that there is a tarball 
@file{lilypond-0.1.73.tar.gz} in the directory @file{../releases}.

If you didn't configure Lily using --srcdir, you can do:

@example 

    make release

    tar-ball: ../patches/lilypond-0.1.73.jcn1.gz
    patch: ../patches/lilypond-0.1.73.jcn1.gz
@end example 

@unnumberedsec Prerequisites
    

For creating a patch you need

@itemize @bullet
@item All items mentioned in @file{INSTALL}.  You're not going to send a patch
    that you haven't even built, right?
@item GNU diff
@example 
    make distclean
    cd ..
    diff -urN lilypond-0.1.73 lilypond-0.1.73.jcn1 > lilypond-0.1.73.jcn1
@end example 

but there are handy python scripts available.  If you're doing development,
you'll need Python for other LilyPond scripts anyway.

@item The Lily directory structure, which looks like:

    @example 

    doos/                        # gnu/windows32 build and binary releases
    harmonia -> harmonia-x.y.z 
    harmonia-x.y.z/
    lilypond -> lilypond-x.y.z   # symlink to development directory
    lilypond-x.y.z/              # current development
    patches/ 		         # patches between different releases
    RedHat/BUILD                 # RedHat build and binary releases
    RedHat/RPMS
    RedHat/SPECS
    releases/                    # .tar.gz releases
    test/                        # tarballs and diffs from current version

 
@end example 

with prefix @file{$HOME/usr/src}
and (for building rpms only) in @file{$HOME/.rpmrc}:
@example 

    topdir: /home/fred/usr/src/RedHat
 
@end example 

@end itemize
	
@unnumberedsec Applying patches
    

If you're following LilyPond development regularly, you probably want to
download just the patch for each subsequent release.
After downloading the patch (into the patches directory, of course), simply 
apply it:

@example 

    gzip -dc ../patches/lilypond-0.1.74.diff.gz | patch -p1 -E
 
@end example 

and don't forget to make automatically generated files:

@example 

    autoconf footnote(patches don't include automatically generated files, 
    i.e. file(configure) and files generated by file(configure).)

    configure
 
@end example 

@unnumberedsec Synchronise
    

If you're not very quick with sending your patch, there's a good
chance that an new release of LilyPond comes available.  In such a
case, the maintainer will probably ask you to make a new patch against
the latest release.  Your best bet is to download the latest release,
and apply your patch against this new source tree:

@example 

    cd lilypond-0.1.74
    gzip -dc ../patches/lilypond-0.1.73.jcn1.diff.gz | patch -p1 -E
    autoconf
    configure
 
@end example 

Then, make a patch as shown above.

@unnumberedsec See also
    

@file{stepmake/INSTALL.txt}

@unnumberedsec maintainer
    

@email{hanwen@@cs.uu.nl, Han-Wen Nienhuys}

Just keep on sending those patches!


@bye
