gnucash/README.patches

############################################################
          Gnucash 1.9.x README.patches file.

NOTE: THIS IS A DEVELOPMENT RELEASE!!! THIS VERSION HAS NOT
BEEN TESTED PROPERLY AND MAY DO ABSOLUTELY ANYTHING!  

USE AT YOUR OWN RISK (AND KEEP *LOTS* OF BACKUPS)

If you want something a bit more tested, please use the
1.6 stable series.
------------------------------------------------------------

Submitting a Patch:

  Once you have done some work that you would like to submit, you need
  to send a patch.  There are two ways to submit a patch.  First, if
  you're using CVS and only made changes to existing CVS files you
  can generate the patch using:

      cvs -q diff -u > /tmp/mypatch

  and send /tmp/mypatch into the developers.  Note that this ONLY WORKS
  if you have NOT added any new files to the source tree.  If you've
  added new files then you should use a script called "make-gnucash-patch"
  to help you create the patch for submission.

  The script make-gnucash-patch is a perl script provided with the
  gnucash distribution that you can use to create your patch.  The
  rest of this file explains how to use that perl script.

  This file comes in two parts:
  - A  quick summary of the common ways to use make-gnucash-patch; and
  - A "users guide" style section giving detailed information on all 
    the options for make-gnucash-patch.

COMMON USAGE

  There are two methods.

  1) Run ./make-gnucash-patch in your source directory.  The script
     will then create two directories ../diff and ../tmp.  In ../tmp
     it will then do a checkout of the cvs sources.  If gnucash has
     already been checked out into this directory then only an update
     will occur.  As a consequence of this you should make sure you
     are merged with current CVS before running make-gnucash-patch or
     you will find parts of the patch are reversing recent changes in
     CVS.

     make-gnucash-patch will then use makepatch to create a patch
     between the original directory and ../tmp/gnucash.  makepatch
     will ask you for a description of the patch. And then the diff
     will be written to the diff file
     ../diffs/gnucash-YYYYMMDD-hhmmss-<username>.diff.gz where Y=year,
     M=month, D=day, h=hour, m=minute, and s=second.

     make-gnucash-patch will then uuencode the diff to
     ../diffs/<samefilename>.uue.

     There are three vars you can set in a ~/.gnucash-patch.rc file.
     The file should look like this

----------------------------------------------------------------------
# -*- perl -*-

$::should_uuencode = 0;
$::ask_description = 0;
$::diffcmd = "diff -up";

1;
----------------------------------------------------------------------
     This is basically a perl file that is sourced by the script.  If
     you don't want the diff to be uuencoded (say you'll send the
     patch in email using mime and don't need it double encoded).  Set
     $::should_uuencode to 0.  If you don't want makepatch to ask you
     for the patch description (so the process is more automated
     possibly) set $::ask_description to 0.  If you want to use a
     different diff command (not recommended for most) set $::diffcmd
     to something else (say, "gdiff -up").

  2) The second method is basically described below but it also
     includes the vars you can set from above.  This method gives you
     more control over which directories are used.

     First, set up your development directories as follows:

     < GnuCash home development directory >
         |
         |---- < directory containing original GnuCash sources >
         |
         |---- < directory containing your modified GnuCash sources >

     A concrete example of those directories might be:

     /home/me/gnucash
         |
         |---- /home/me/gnucash/gnucash.pristine (original sources)
         |
         |---- /home/me/gnucash/gnucash.mywork (original sources + my edits)

     Copy the make-gnucash-patch script to the home development
     directory (/home/me/gnucash above). Now set three environment
     variables to reflect the names of your directories. Given the
     names above, you would use:

     export GNC_MAKEPATCH_OLD_DIR=gnucash.pristine
     export GNC_MAKEPATCH_NEW_DIR=gnucash.mywork
     export GNC_MAKEPATCH_HOME_DIR=/home/me/gnucash

     Right before you make your patch, make sure *both* your working
     and your pristine directories are in sync with cvs. Run 'cvs -z3
     update -dP' in both directories to ensure that is the
     case. Updating from cvs in your working directory may cause
     conficts in a file. You must resolve those conficts before making
     a patch.

     Now run the script. Note that this script requires the programs
     'makepatch', 'gzip', a 'diff' work-a-like, and 'uuencode' (and, of
     course, 'perl') to run.

     The same files will be generated for this method as the last
     (../diffs/*.diff.gz and ../diffs/*.diff.gz.uue).

USERS GUIDE

 make-gnucash-patch supports a number of ways of providing required
 information. Some information can be provided through the use of 
 environment variables or in the .gnucash-patch.rc file in your 
 home directory. All information can be provided by command-line
 options.

 In all cases, the options given on the command-line override the
 information in both environment variables and the .gnucash-patch.rc
 file.
 Environment variables (where permitted) will override the
 .gnucash-patch.rc file.

 The general format for using make-gnucash-patch is:
      ./make-gnucash-patch <options>

 where valid options are (in arbitrary order):
 --help, --h          Display a short help message explaining available
                      options.

 --prefix "homedir"   Specifies the home directory path to use. This path is
                      prepended to both the new and old directory names to
                      give the full path for those directories.
                      Defaults to:  the parent directory.
                      Environment variable: GNC_MAKEPATCH_HOME_DIR

 --old "olddir"       The name of the directory containing the "pristine" or
                      unmodified copy of the gnucash CVS tree.
                      The directory path as determined by --prefix is prepended
                      to this name to give the full directory path.
                      Defaults to:  ../tmp and will create if it doesn't exist.
                      Environment variable: GNC_MAKEPATCH_OLD_DIR

 --new "newdir"       The name of the directory containing the modified copy of
                      the gnucash CVS tree. 
                      The directory path as determined by --prefix is prepended
                      to this name to give the full directory path.
                      Defaults to:  the current directory.
                      Environment variable: GNC_MAKEPATCH_NEW_DIR

 --diff "diffname"    The name to give to the output ("diff") file containing
                      the patch code.
                      Defaults to:  gnucash-YYYYMMDD-HHmmSS-XXXX.diff
                       where: YYYY = current year (4 digit form)
                              MM   = current month (2 digit form)
                              DD   = current date (2 digit form)
                              HH   = current hour (24-hour 2 digit form)
                              mm   = current minutes (2 digit form)
                              SS   = current seconds (2 digit form)
                              XXXX = userid of current user (arbitrary length)
 
 --diffcmd "command"  The command to give to makepatch to generate the
                      differences between two files.
                      *NOT* Recommended for most users, only for those whom
                      diff -up is non-functional. 
                      Defaults to:  diff -up

 --file "filename"   Generate a patch for ONLY this file. The path within
                     the CVS tree must be specified (eg. src/MultiLedger.c) or 
                     the file cannot be matched. You can specify multiple files
                     by seperating them by commas. You can also include this
                     option multiple times.
                     You *CANNOT* use this option with wildcards, regexps, or
                     partial matches.
                     Defaults to:  none.
                     See Also: --manifest

 --manifest "file"   Use "file" as a manifest file (file that contains a list
                     of all files to be compared in the making of the diff).
                     Manifest files must contain one filename per line. Lines 
                     starting with # are ignored.

--ignore "igname"    Name of the file in the parent directory which contains
                     regular expressions matching files which are to be excluded
                     from the patch. This is in addition to a number of files
                     which are automatically excluded by the script.
                     Defaults to:  none.

 --uuencode          Specifies whether the resultant diff file should be
 --nouuencode        uuencoded or not. uuencoding is a way of encrypting the file
                     so that it is less likely to be corrupted during transmission
                     over the internet. You should generally use it.
                     Defaults to: On.
                     .gnucash-patch.rc file:  Yes 
                          ("$::should_uuencode = 0;" to override default).

 --zip               Specifies whether the resultant diff file should be
 --nozip             compressed or not. This is not always necessary when the
                     patch is a small one.
                     Defaults to:  On.

 --ask               Controls whether makepatch should ask for a description of
 --noask             this patch or not.
                     Defaults to:  On.
                     .gnucash-patch.rc file:  Yes
                          ("$::ask_description = 0;" to override default).


THINGS TO NOTE
 - the script assumes (when using defaults) that it is being executed in the 
   top directory of the modified CVS tree. This can be overridden by specifying
   prefix, old, and new directories.
 - the script assumes that both the "pristine" and modified copy are children
   of the same parent directory.
 - the script will check out a "pristine" copy of the CVS tree automatically if
   it cannot find the old directory you specify. 


     Thanks in advance for your contribution!