Patches

What is a patch

Patches are usually textual differences between two source code files, called "diffs". Unless the code is written in a script language, it is required to compile the new or changed files themselves. The idea of a patch is to only transfer source code differences, which reduces the code volume being transferred while improving the readability of the changes.

Below a random example (see also trac r67296):

Index: /grass/trunk/lib/raster/open.c
===================================================================
--- /grass/trunk/lib/raster/open.c	(revision 67295)
+++ /grass/trunk/lib/raster/open.c	(revision 67296)
@@ -231,5 +231,8 @@
 	    cellhd.compressed = 2;
     }
-    /* TODO: test if compressor type is supported */
+    /* test if compressor type is supported */
+    if (!G_check_compressor(cellhd.compressed)) {
+	G_fatal_error(_("Compression with %s is not supported"), G_compressor_name(cellhd.compressed));
+    }
 
     if (cellhd.proj != R__.rd_window.proj)
@@ -649,6 +652,6 @@
      */
     fcb->cellhd = R__.wr_window;
-
-    /* TODO: test if compressor type is supported */
+    
+    /* change open_mode to OPEN_NEW_UNCOMPRESSED if R__.compression_type == 0 ? */
 
     if (open_mode == OPEN_NEW_COMPRESSED && fcb->map_type == CELL_TYPE) {

From these changes it is evident what has been updated in the code.

Creating a patch

The creation of a patch occurs when having applied changes to the source code locally. In order to distribute them (mailing list; upload to the SVN repository), you need to do the following:

• 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 v.in.ascii.html and your locally edited v.in.ascii.html (example):

 svn diff vector/v.in.ascii/v.in.ascii.html > v.in.ascii.description.diff

The "diff -u" command will create the file v.in.ascii.description.diff which shows any differences between the version of v.in.ascii.html still on the SVN 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 v.in.ascii.html in SVN (see also above for an example). The exact name of your patch file is arbitrary, but should be as descriptive as possible as in the above example.

To provide this context diff file, create it from the top level source directory (the one with GPL.TXT in it). Otherwise it is sometimes hard to know to find the referring file (especially, when it is main.c.

Applying a patch

If you receive a pathc (diff) file (e.g. via mailing list; downloaded from SVN), copy the patch file into the given directory which is usually the root GRASS GIS source code 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 (-p1 or whatever).

Downloading patches from SVN

We use the GRASS GIS bugtracker for the management of most patches in order to keep a record. Our best practice is also to refer to bug numbers and changesets (patches applied in SVN, numbered like revision rXXXXX) in the SVN commit log entries (for examples, see the timeline). Thanks to this practice we can easily trace back changes which is also useful for backporting them from the development branch (trunk) to the release branch(es).

Trac tickets sometimes carry as attachments patches. In order to try them locally, download them as follows:

• Open the respective ticket
  • --> Attachments
    • --> open patch link
      • --> scroll to page bottom: "Download in other formats: Unified Diff"

Then apply as outlined below.

Submitting patches

• Email it to the grass-dev mailing list or a GRASS developer your patch file for review as an attachment, along with a brief explanation why it is required.

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 GRASS trac system. If only posted to the mailing lists they will be archived but risk being forgotten.