
notableofcontents()
article(PATCHES - track and distribute your code changes)()()

This page documents how to distribute your changes to Yodl
(or in fact any other StepMake package).

nsect(ABSTRACT)

Distributing a change normally goes like this:

itemize(
it()make your fix/add your code 
it()Add changes to NEWS, and add yourself to Documentation/AUTHORS.yo
it()generate a patch, 
it()e-mail your patch to the mailing list email(yodl@icce.rug.nl)
    
)

nsect(GENERATING A PATCH)

In file(VERSION), set MY_PATCH_LEVEL:

verb(
    VERSION:
	...
	MY_PATCH_LEVEL=jcn1
)

In file(NEWS), enter a summary of changes:

verb(
    NEWS:
	pl 1.30.0.jcn1
		- added PATCHES.yo
)

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

verb(
    make dist
    make diff
)

which rolls the tarball file(../releases/yodl-1.30.0.jcn1.diff)
and leaves your patch as file(./yodl-1.30.0.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(yodl-1.30.0.tar.gz) in the directory file(../releases).

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

verb(
    make release

    tar-ball: ../patches/yodl-1.30.0.jcn1.gz
    patch: ../patches/yodl-1.30.0.jcn1.gz
    updeet: ../test/updeet
)

nsect(PREREQUISITES)

For creating a patch you need

itemize(
it()All items mentioned in file(INSTALL).  You're not going to send a patch
    that you haven't even built, right?
it()GNU Diff
it()Python (version 1.4 or newer).  
    You can of course make a patch by hand, which would go something like:

verb(
    make distclean
    cd ..
    diff -urN yodl-1.30.0 yodl-1.30.0.jcn1 > yodl-1.30.0.jcn1
)

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

it()The Yodl directory structure, which looks like:

includefile(../include/layout.yo)
)
	
nsect(APPLYING PATCHES)

If you're following Yodl 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:

verb(
    gzip -dc ../patches/yodl-1.30.1.gz | patch -p1 -E
)

and don't forget to make automatically generated files:

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

    configure
)

nsect(SYNCHRONISE)

If you're not very quick with sending your patch, there's a good chance
that an new release of Yodl comes available.  In such a case (and
sometimes for other unkown reasons :-), 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:

verb(
    cd yodl-1.30.1
    gzip -dc ../patches/yodl-1.30.0.jcn1.diff.gz | patch -p1 -E
    autoconf
    configure
)

Then, make a patch as shown above.

nsect(SEE ALSO)

code(stepmake/INSTALL.txt)

nsect(MAINTAINER)

nemail(Jan Nieuwenhuizen)(janneke@gnu.org)

Just keep on sending those patches!

