Patches: Difference between revisions

From GRASS-Wiki
Jump to navigation Jump to search
m (added category)
No edit summary
 
(7 intermediate revisions by 2 users not shown)
Line 1: Line 1:
__TOC__
__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 ==
== 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:
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.


<!--  cvs diff -u description.html > v.in.ascii.description.patch
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:
    or -->
  svn diff vector/v.in.ascii/description.html > v.in.ascii.description.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 <tt>v.in.ascii.html</tt> and your locally edited <tt>v.in.ascii.html</tt> (example):


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


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):
A patch file is containing only the relative changes to a current state of the source code or documentation.
<pre>
 
Index: description.html
Patch files are commonly distributed in two main ways:
===================================================================
* as an attachment to an email;
RCS file: /home/grass/grassrepository/grass6/vector/v.in.ascii/description.html,v
* as an attachment to a bug report (so-called "ticket").
retrieving revision 1.35
 
diff -u -r1.35 description.html
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.
--- description.html    31 May 2006 13:03:57 -0000      1.35
 
+++ description.html    26 Sep 2006 14:35:21 -0000
== Downloading patches from SVN ==
@@ -35,6 +35,10 @@
 
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:


Use the <b>-z</b> flag to convert ASCII data into a 3D binary vector map.
* 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"


+Any edits you make to description.html will show up like this after you run diff -u!
Alternatively, you can click on the little download icon next to the link (encircled in red in the screenshot below):
+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
[[File:downloadlink_screenshot.png|frame|left|Screenshot of link to patch file in trac ticket]]
primitive code, the total number of vectors in the series, and the number
<br clear=all>Then apply as outlined below.
</pre>


== Applying a patch ==
== Applying a patch locally ==


Copy the patch into the given directory and run:
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
  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.''



Latest revision as of 14:54, 15 September 2016

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

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.