Patches - Revision history

Neteler at 14:54, 15 September 2016

2016-09-15T14:54:33Z

← Older revision		Revision as of 14:54, 15 September 2016
Line 80:		Line 80:
	* as an attachment to a bug report (so-called "ticket").		* 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~~: "Download in other formats:" --> "Original Format"~~.		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.

	~~Save~~ the ~~file and read on below :-)~~

	~~== Applying a patch ==~~

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

	== Downloading patches from SVN ==		== Downloading patches from SVN ==
Line 107:		Line 97:
	[[File:downloadlink_screenshot.png\|frame\|left\|Screenshot of link to patch file in trac ticket]]		[[File:downloadlink_screenshot.png\|frame\|left\|Screenshot of link to patch file in trac ticket]]
	<br clear=all>Then apply as outlined below.		<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 ==		== 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.		* 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.''

Neteler: improved

2016-09-15T14:52:36Z

improved

← Older revision		Revision as of 14:52, 15 September 2016
Line 58:		Line 58:

	=== Preparing a patch ===		=== Preparing a patch ===
	In order to distribute a patch made by you (to the grass-dev mailing list; or for upload to ~~the SVN repository~~), you need to do the following:
			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):		* 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):

Neteler: +Obtaining a patch

2016-09-15T14:49:25Z

+Obtaining a patch

← Older revision		Revision as of 14:49, 15 September 2016
Line 68:		Line 68:

	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>.		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: "Download in other formats:" --> "Original Format".

			Save the file and read on below :-)

	== Applying a patch ==		== 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:		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

Neteler: + svn download

2016-04-29T18:08:33Z

+ svn download

@@ Line 37: / Line 37: @@
 == 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 creation of a patch occurs when having applied changes to the source code locally.
 * 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):

⚠️Pvb: edits

2015-12-23T15:17:14Z

edits

← Older revision		Revision as of 15:17, 23 December 2015
Line 62:		Line 62:
	Trac tickets sometimes carry as attachments patches. In order to try them locally, download them as follows:		Trac tickets sometimes carry as attachments patches. In order to try them locally, download them as follows:

	* Open the respective ~~[https://trac~~.~~osgeo~~.~~org/grass/roadmap ticket]~~		* Open the respective ticket using the link (e.g., the red text in the screenshot below)
	** --> Attachments		** --> Attachments
	*** --> open patch link		*** --> open patch link
Line 69:		Line 69:
	Alternatively, you can click on the little download icon next to the link (encircled in red in the screenshot below):		Alternatively, you can click on the little download icon next to the link (encircled in red in the screenshot below):

	[[File:downloadlink_screenshot.png\|left]]		[[File:downloadlink_screenshot.png\|frame\|left\|Screenshot of link to patch file in trac ticket]]
	<br clear=all>Then apply as outlined below.		<br clear=all>Then apply as outlined below.

⚠️Pvb: added screenshot with download link for patch files

2015-12-23T15:11:50Z

added screenshot with download link for patch files

← Older revision		Revision as of 15:11, 23 December 2015
Line 67:		Line 67:
	**** --> scroll to page bottom: "Download in other formats: Unified Diff"		**** --> scroll to page bottom: "Download in other formats: Unified Diff"

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

			[[File:downloadlink_screenshot.png\|left]]
			<br clear=all>Then apply as outlined below.

	== Submitting patches ==		== Submitting patches ==

Neteler: +Downloading patches from SVN

2015-12-23T11:44:41Z

+Downloading patches from SVN

@@ Line 55: / Line 55: @@
 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.''

Neteler: updated

2015-12-22T16:26:48Z

updated

← Older revision		Revision as of 16:26, 22 December 2015
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.''

⚠️MilenaN: added category

2010-08-02T23:35:45Z

added category

← Older revision		Revision as of 23:35, 2 August 2010
Line 61:		Line 61:

	* 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.		* 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]]

⚠️HamishBowman: /* Creating a patch */ full path

2008-12-11T01:50:32Z

Creating a patch: full path

← Older revision		Revision as of 01:50, 11 December 2008
Line 7:		Line 7:
	<!-- cvs diff -u description.html > v.in.ascii.description.patch		<!-- cvs diff -u description.html > v.in.ascii.description.patch
	or -->		or -->
	svn diff description.html > v.in.ascii.description.patch		svn diff vector/v.in.ascii/description.html > v.in.ascii.description.patch


	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 ~~CVS~~ 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		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
	possible as in the above example.		possible as in the above example.