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 the first place you need the source code from SVN:

Getting the source code

To extract the current GRASS GIS 7.0.x release branch version (stable), which continuously receives bugfixes, use the command:

# one time only download:
svn checkout https://svn.osgeo.org/grass/grass/branches/releasebranch_7_0 grass70_release

# subsequent updates:
cd grass70_release/
svn up

See also: https://trac.osgeo.org/grass/wiki/DownloadSource

Now you can modify the source code, correct grammar, add new functionality and so on.

Preparing a patch

After own coding or improvement of documentation (which is essentially managed like source code) you may want to share your changes. To avoid that entire files are floating around, just the differences to the official state of source code or documentation is distributed, a so-called "patch" or "diff" file.

In order to distribute a patch made by you (to the grass-dev mailing list; or for upload to trac), 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.

Obtaining a patch

A patch file is containing only the relative changes to a current state of the source code or documentation.

Patch files are commonly distributed in two main ways:

• as an attachment to an email;
• as an attachment to a bug report (so-called "ticket").

The GRASS GIS project uses https://trac.osgeo.org/grass/ to manage the source code. In order to download a patch from trac, expand the "attachment" section of a bug report, click onto the attached patch and scroll down to the page bottom (following the visual changes, there is a link to actually download the file in order to apply it for testing to a local source code copy. See the next section.

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 using the link (e.g., the red text in the screenshot below)
  • --> Attachments
    • --> open patch link
      • --> scroll to page bottom: "Download in other formats: Unified Diff"

Alternatively, you can click on the little download icon next to the link (encircled in red in the screenshot below):

Screenshot of link to patch file in trac ticket

Then apply as outlined below.

Applying a patch locally

If you receive a patch (a so-called "diff") file (e.g. via mailing list; downloaded from trac as attachment to a ticket), 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).

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.