Difference between revisions of "Patches"

From GRASS-Wiki
Jump to: navigation, search
m (added category)
(updated)
Line 1: Line 1:
 
__TOC__
 
__TOC__
  
== Creating a patch ==
+
== What is 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:
+
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.
  
<!--  cvs diff -u description.html > v.in.ascii.description.patch
+
Below a random example (see also {{changeset|67296}}):
    or -->
 
  svn diff vector/v.in.ascii/description.html > v.in.ascii.description.patch
 
  
 +
<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>
  
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 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 description.html. The exact name of your patch file is arbitrary, but should be as descriptive as
+
From these changes it is evident what has been updated in the code.
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.
+
== 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:
  
The output of the diff -u should look <i>something</i> like this (the exact contents will of course depend on whatever changes you made to the file):
+
* 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):
<pre>
 
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.
+
  svn diff vector/v.in.ascii/v.in.ascii.html > v.in.ascii.description.diff
  
+Any edits you make to description.html will show up like this after you run diff -u!
+
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
+Three lines of the original description.html will surround each block of edits you made
+
possible as in the above example.
+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
+
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>.
primitive code, the total number of vectors in the series, and the number
 
</pre>
 
  
 
== Applying a patch ==
 
== Applying a patch ==
  
Copy the patch into the given directory and run:
+
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
 
  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.
+
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 ==
 
== Submitting patches ==
  
* Email a [http://grass.osgeo.org/community/team.php GRASS developer] your description.html.patch for review <i>as an attachment</i>, along with a brief explanation why it is required. Please post a general message about your documentation update to the [http://grass.osgeo.org/devel/index.php#list GRASS Developer's List] before sending your patch to anyone in particular.
+
* 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.''
 
: ''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.''
  

Revision as of 09:26, 22 December 2015

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).

Submitting patches

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.