Patches

Creating a patch

• Within a terminal, create a 'unified diff' (a standard way to show changes between two versions of a file) of the GRASS SVN repository version of description.html and your newly edited description.html:

 cvs diff -u description.html > v.in.ascii.description.patch
   or
 svn diff description.html > v.in.ascii.description.patch

The "diff -u" command will create a report in v.in.ascii.description.patch which shows any differences between the version of description.html still on the CVS server and your edited version; a '+' at the beginning of each line denotes edits and additions you have made, and a '-' at the beginning of each line denotes lines removed from the original description.html. The exact name of your patch file is arbitrary, but should be as descriptive as possible as in the above example.

To provide filename context diff should ideally be run from the top level source directory (the one with GPL.TXT in it). Otherwise it is hard to know which 'description.html' is being referred to, as each of the 400 GRASS modules has one.

The output of the diff -u should look something like this (the exact contents will of course depend on whatever changes you made to the file):

Index: description.html
===================================================================
RCS file: /home/grass/grassrepository/grass6/vector/v.in.ascii/description.html,v
retrieving revision 1.35
diff -u -r1.35 description.html
--- description.html    31 May 2006 13:03:57 -0000      1.35
+++ description.html    26 Sep 2006 14:35:21 -0000
@@ -35,6 +35,10 @@

 Use the <b>-z</b> flag to convert ASCII data into a 3D binary vector map.

+Any edits you make to description.html will show up like this after you run diff -u!
+Three lines of the original description.html will surround each block of edits you made
+to provide context.
+
 A GRASS ASCII vector file (in <B>standard</B> mode) may contain a mix of
 primitives including points, lines, boundaries, centroids, areas, faces,
@@ -51,6 +55,8 @@
 <LI>'K': kernel (3D centroid)</LI>
 <LI>'A': area (boundary) - better use 'B'; kept only for backward compatibility</LI>
 </UL>
+
+This line is another edit made further along in description.html....

The coordinates are listed following the initial line containing the
 primitive code, the total number of vectors in the series, and the number

Applying a patch

Copy the patch into the given directory and run:

patch -p0 < the_patch_file.diff

If the patch was created from the top source directory, apply it from there. (the path will be included in the filename at the start of the diff) If applying from outside of the directory level the patch was made from, adjust -p0 as needed.

Submitting patches

• Email a GRASS developer your description.html.patch for review as an attachment, along with a brief explanation why it is required. Please post a general message about your documentation update to the GRASS Developer's List before sending your patch to anyone in particular.

Small patches sent to the grass-dev mailing list for demonstration purposes should be sent as an attachment because if they are simply cut and pasted into an email the email client can/will line wrap the patch, breaking its machine readability.

• Larger patches and patches officially submitted for consideration should be posted to the appropriate GRASS patch tracker. If only posted to the mailing lists they will be archived but risk being forgotten.