View source for Patches

__TOC__

== 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 {{changeset|67296}}):

<source lang="diff">
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) {
</source>

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:

<pre>
# 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
</pre>

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 [https://lists.osgeo.org/pipermail/grass-dev/ grass-dev mailing list]; or for upload to [https://trac.osgeo.org/grass/ 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 <tt>v.in.ascii.html</tt> and your locally edited <tt>v.in.ascii.html</tt> (example):

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

The "diff -u" command will create the file <tt>v.in.ascii.description.diff</tt> which shows any differences between the version of <tt>v.in.ascii.html</tt> 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 <tt>v.in.ascii.html</tt> 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 <tt>main.c</tt>.

== 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 [https://trac.osgeo.org/grass/ 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 [https://trac.osgeo.org/grass/timeline 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):

[[File:downloadlink_screenshot.png|frame|left|Screenshot of link to patch file in trac ticket]]
<br clear=all>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 [https://lists.osgeo.org/mailman/listinfo/grass-dev grass-dev mailing list] or a [https://grasswiki.osgeo.org/wiki/Team GRASS developer] your patch file for review <i>as an attachment</i>, 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 [http://trac.osgeo.org/grass/newticket GRASS trac system]. If only posted to the mailing lists they will be archived but risk being forgotten.

[[Category: Development]]