Difference between revisions of "Working with SVN"

From GRASS-Wiki
Jump to: navigation, search
m (Category:MoveToTrac)
 
(11 intermediate revisions by 3 users not shown)
Line 1: Line 1:
[''I find the main grass website CVS help pages many, complex, and confusing. So trying to start over here with a more concise help page'']
+
{{MoveToTrac}}
  
== Tips for everyone ==
 
  
* You can setup default CVS options in a file called .cvsrc in your home directory.
+
[''I find the main GRASS website SVN help pages many, complex, and confusing. So trying to start over here with a more concise help page'']
cat << EOF >> ~/.cvsrc
+
 
-z3
+
== SVN Overview ==
diff -u
+
 
update -dP
+
Collaborative source code management using CVS or Subversion (SVN) keeps track of source code changes in a central spot and handles all the accounting work needed to cleanly handle version numbers and change history.
EOF
+
 
 +
A SVN repository contains a trunk (aka HEAD), branches, and tags.
 +
 
 +
=== What are branches and tags? ===
 +
 
 +
SVN (the collaborative source code repository and tracking system we use) is broken down into three distinct parts: repositories, branches, and tags.
 +
 
 +
http://trac.osgeo.org/grass/browser/grass/
 +
 
 +
1. '''trunk'''. contains all source code and history for a project. aka ''HEAD''
 +
: for example ''grass'' (for grass 5.x), ''grass6'' (grass 6.x),
 +
 
 +
2. '''branches'''. at a certain date it is split off from ''HEAD''. New developement in ''HEAD'' will not appear in the branch, changes must be backported to the branch. Usually created in advance of a stable release to separate code that is trying to be stabilized from new development.
 +
: for example ''releasebranch_6_0'' or ''releasebranch_6_2'' in the ''grass6'' repository for GRASS 6.0.x and GRASS 6.2.x
 +
 
 +
3. '''tag'''. a branch snapshot, technically an alias to a date stamp in a branch
 +
: for example ''release_20071127_grass_6_2_3'' in the ''releasebranch_6_2'' branch for the GRASS 6.2.3 release
 +
 
 +
4. also the GRASS Web site pages are managed in SVN: http://trac.osgeo.org/grass/browser/grass-web
 +
 
 +
5. also the GRASS Addons are managed in SVN: http://trac.osgeo.org/grass/browser/grass-addons
 +
 
 +
=== Implementation ===
 +
 
 +
The general principle is that no new development occurs on a release branch.
 +
 
 +
Development occurs on a development branch (or the trunk). When it is deemed time for a new series of releases, a the development branch is forked to create a release branch, and a snapshot of the release branch is created to form the first release candidate. Thereafter, the only modifications to the release branch are made by merging specific changes from the development branch to the release branch. The various release candidates and releases are snapshots of the release branch.
  
* Explore the CVS tree and file history with the [http://freegis.org/cgi-bin/viewcvs.cgi/grass6/ WebCVS interface].
+
This means that changes whose desirability is uncertain can be made to the development branch. If they work out, they get merged onto the release branch. If they don't work out, they simply don't get merged; there is no need to explicitly back them out to obtain a stable version for release.
  
== Tips for users ==
+
== Tips for everyone ==
(read-only access to the latest code)
+
 
 +
* Explore the SVN tree and file history with the [http://trac.osgeo.org/grass/browser/grass Web interface].
  
 
=== Setting it up (first time) ===
 
=== Setting it up (first time) ===
  
 
* Download latest source code snapshot
 
* Download latest source code snapshot
  wget http://grass.itc.it/grass63/source/snapshot/grass-6.3.cvs_src_snapshot_${DATE}.tar.gz
+
  wget [http://grass.osgeo.org/grass64/source/snapshot/ http://grass.osgeo.org/grass64/source/snapshot/]grass-6.4.svn_src_snapshot_${DATE}.tar.gz
 
* move it somewhere on your filesystem ''without'' spaces or special characters in the path.
 
* move it somewhere on your filesystem ''without'' spaces or special characters in the path.
  mv grass-6.3.cvs_src_snapshot_${DATE}.tar.gz /usr/local/src/
+
  mv grass-6.4.svn_src_snapshot_${DATE}.tar.gz /usr/local/src/
 
* decomress it
 
* decomress it
  tar xzf grass-6.3.cvs_src_snapshot_${DATE}.tar.gz
+
  tar xzf grass-6.4.svn_src_snapshot_${DATE}.tar.gz
 
* at this stage, you may want to rename the source directory to something shorter
 
* at this stage, you may want to rename the source directory to something shorter
  mv grass-6.3.cvs_src_snapshot_${DATE}/ grass63/
+
  mv grass-6.4.svn_src_snapshot_${DATE}/ grass64svn/
  cd grass63/
+
  cd grass64svn/
* set for anonymous connection to CVS server
+
* update to the latest code
CVSROOT=:pserver:grass-guest@intevation.de:/home/grass/grassrepository
+
  svn update
export CVSROOT
 
* login to CVS
 
cvs login
 
password: grass
 
* update to the latest
 
  cvs -z3 update -dP
 
  
=== Updating entire source tree (second time) ===
+
=== Updating entire source tree (another time) ===
The is no need to login to CVS now, it remembers all that.
 
  
* clear away the existing rubble
+
For future updates, do:
 +
 
 +
* clear away the existing rubble (recommended if lib/gis/ changed)
 
  make distclean
 
  make distclean
* update (You can skip the reporting of all directories by adding the -q flag (assumes -z3 and -dP were added to ~/.cvsrc)
+
* update
  cvs -q update
+
  svn update
 
* re run ./configure and make
 
* re run ./configure and make
  
Line 49: Line 70:
 
* for example, updating just the r.cost module
 
* for example, updating just the r.cost module
 
  cd raster/r.cost
 
  cd raster/r.cost
  cvs up
+
  svn up
 
  make
 
  make
 +
 +
(and 'make install' in the main directory if you always install the software)
  
 
* If includes/ or module header files (*.h) have changed, you will have to run
 
* If includes/ or module header files (*.h) have changed, you will have to run
Line 65: Line 88:
 
* SUBMITTING_SCRIPTS
 
* SUBMITTING_SCRIPTS
 
* SUBMITTING_TCLTK
 
* SUBMITTING_TCLTK
 +
* SUBMITTING_PYTHON
 +
* SUBMITTING_DOCS
  
 
=== Legal issues ===
 
=== Legal issues ===
Line 89: Line 114:
 
  #              Imports single and split E00 files (.e00, .e01, .e02 ...)
 
  #              Imports single and split E00 files (.e00, .e01, .e02 ...)
 
  #
 
  #
  # COPYRIGHT:    (c) 2004, 2005 GDF Hannover bR, http://www.gdf-hannover.de
+
  # COPYRIGHT:    (c) 2004, 2005 GRASS Development Team and GDF Hannover bR, http://www.gdf-hannover.de
 
  #
 
  #
 
  #              This program is free software under the GNU General Public
 
  #              This program is free software under the GNU General Public
Line 103: Line 128:
 
==== Due diligence ====
 
==== Due diligence ====
  
* PSC RFC2
+
* [[PSC]] - [http://download.osgeo.org/grass/grass6_progman/rfc/ RFC2]
  
 
=== Code submission method ===
 
=== Code submission method ===
  
(Note: this applies to people without CVS write access)
+
(Note: this applies to people without SVN write access)
  
'''Be sure to develop on top of the LATEST GRASS code (CVS HEAD), ''not'' on top of a stable branch.'''
+
'''Be sure to develop on top of the LATEST GRASS code (SVN HEAD), ''not'' on top of a stable branch.'''
  
 
You can re-check before submission with:
 
You can re-check before submission with:
  cvs diff -u
+
  svn diff
  
 
==== Preparing a patch ====
 
==== Preparing a patch ====
  
* create a unidiff patch against the latest development branch CVS
+
* ''See the wiki page describing [[Patches]].''
  
Be sure to create unified ("diff -u") format. "Plain" diffs (the default
+
* Create a Unidiff patch against the latest development branch  SVN (trunk).
format) are risky, because they will apply without warning to code which
+
 
has been substantially changed; they are also harder to read than unified.
+
Be sure to create them in unified ("diff -u") format. "Plain" diffs (the default format) are risky, because they will apply without warning to code which has been substantially changed; they are also harder to read than unified. The default for '<tt>svn diff</tt>' is to create a unidiff.
  
 
Such diffs should be made from the top-level directory, e.g.
 
Such diffs should be made from the top-level directory, e.g.
"cvs diff -u display/d.vect/main.c"; that way, the diff will
+
"<tt>svn&nbsp;diff&nbsp;display/d.vect/main.c</tt>"; that way, the diff will include the pathname rather than just the generic "main.c".
include the pathname rather than just "main.c".
 
  
Imagine, that You have hacked around in module r.foo. To create patch, You should use following commands:
+
Imagine that You have hacked around in module r.foo. To create a patch you should use following commands:
   cd /path/to/grass6
+
   cd /path/to/grass7
   cvs diff -u raster/r.foo > r.foo.patch
+
   svn diff raster/r.foo > r.foo.patch
  
 
==== Applying someone else patch ====
 
==== Applying someone else patch ====
  
To apply patch created by someone else using "cvs diff" command, You need to use following command:
+
To apply patch created by someone else using "svn diff" command, You need to use following command:
   cd /path/to/grass6
+
   cd /path/to/grass7
 
   patch -p0 < /path/to/r.foo.patch
 
   patch -p0 < /path/to/r.foo.patch
  
Line 140: Line 164:
 
The GEM system makes it easy to prepare intergrated add-on modules or groups of add-on modules as extensions to the existing GRASS source code. Users do not need to build the entire GRASS source package to add and build GEM packages.
 
The GEM system makes it easy to prepare intergrated add-on modules or groups of add-on modules as extensions to the existing GRASS source code. Users do not need to build the entire GRASS source package to add and build GEM packages.
  
* link to GEM add-on docs
+
* {{cmd|gem/index}} documentation
  
 
==== Submitting it to the Wiki Add-Ons page ====
 
==== Submitting it to the Wiki Add-Ons page ====
Line 148: Line 172:
  
 
==== Submitting it to the code tracker ====
 
==== Submitting it to the code tracker ====
Non-trival formal patches which are expected to become part of the main GRASS source tree should be uploaded to the "code patches" tracker and GRASS's Gforge site.
+
Non-trival formal patches which are expected to become part of the main GRASS source tree should be uploaded to the "code patches" tracker and GRASS's trac site.
  
* http://wald.intevation.org/projects/grass/
+
* http://trac.osgeo.org/grass/
  
 
==== Announcing it on the GRASS Development mailing list ====
 
==== Announcing it on the GRASS Development mailing list ====
  
Once it is uploaded to the Wiki Add-ons page or the Gforge code tracker, announce it on the [http://grass.ibiblio.org/devel/index.php#list GRASS-dev mailing list].
+
Once it is uploaded to the [[Wiki AddOns]] page or the trac code tracker, announce it on the [http://grass.osgeo.org/devel/index.php#list GRASS-dev mailing list].
  
 
Final products added to the Wiki Add-Ons page should be announced on the GRASS users' mailing list.
 
Final products added to the Wiki Add-Ons page should be announced on the GRASS users' mailing list.
Line 160: Line 184:
 
==== Getting help ====
 
==== Getting help ====
  
* IRC
+
* [http://grass.osgeo.org/community/support.php#irc IRC] - Internet Relay Chat
* [http://grass.ibiblio.org/devel/index.php#list GRASS-dev mailing list]
+
* [http://grass.osgeo.org/devel/index.php#list GRASS-dev mailing list]
  
 
== Tips for GRASS developers ==
 
== Tips for GRASS developers ==
(CVS write access, committing)
+
(SVN write access, committing)
  
 
=== Becoming a GRASS developer ===
 
=== Becoming a GRASS developer ===
  
 
The [[PSC|GRASS Project Steering Committee]] is in charge of giving new developers write access to the CVS. This generally happens after the developer has been submitting code for long enough for the other developers to become familiar with the person and their coding ability.
 
The [[PSC|GRASS Project Steering Committee]] is in charge of giving new developers write access to the CVS. This generally happens after the developer has been submitting code for long enough for the other developers to become familiar with the person and their coding ability.
 +
 +
Read on here: http://trac.osgeo.org/grass/wiki/HowToContribute
  
 
=== Responsibilities ===
 
=== Responsibilities ===
  
* [http://freegis.org/cgi-bin/viewcvs.cgi/grass6/rfc/RFC2_PSC.dox?rev=HEAD&content-type=text/vnd.viewcvs-markup RFC2: Legal aspects of code contributions]
+
* [http://download.osgeo.org/grass/grass6_progman/rfc/ RFC2: Legal aspects of code contributions]
* follow the [http://grass.itc.it/devel/index.php#submission code submission guidelines]
+
* follow the [http://grass.osgeo.org/devel/index.php#submission code submission guidelines]
  
 
=== Setting it up ===
 
=== Setting it up ===
  
* Connection to CVS with write access: ssh, firewalls, login, etc.
+
* Connection to SVN with write access: see [http://trac.osgeo.org/grass/wiki/HowToSVN here]
** See [http://freegis.org//grass/howto_grass-sshcvs.en.html  GRASS-CVS-ssh instructions]
 
  
 
* configuring GRASS for code development:
 
* configuring GRASS for code development:
Line 190: Line 215:
 
=== Commiting ===
 
=== Commiting ===
  
* work against latest development branch CVS HEAD (update before committing)
+
* work against latest development SVN HEAD (update before committing)
 
* code must compile
 
* code must compile
* verify changes with 'cvs diff -u' before all commits
+
* verify changes with 'svn diff' before all commits
* cvs commit: make the cvs log message a useful synopsis of the change
+
* cvs commit: make the svn log message a useful synopsis of the change (svn2cl script)
* double check the change using the live WebCVS interface or [http://grass.itc.it/mailman/listinfo/grass-commit grass-commit mailing list]
+
* double check the change using the live WebSVN interface or [http://lists.osgeo.org/mailman/admin/grass-qa grass-qa mailing list]
 +
 
 +
[[Category:Development]]

Latest revision as of 03:30, 9 February 2013


[I find the main GRASS website SVN help pages many, complex, and confusing. So trying to start over here with a more concise help page]

SVN Overview

Collaborative source code management using CVS or Subversion (SVN) keeps track of source code changes in a central spot and handles all the accounting work needed to cleanly handle version numbers and change history.

A SVN repository contains a trunk (aka HEAD), branches, and tags.

What are branches and tags?

SVN (the collaborative source code repository and tracking system we use) is broken down into three distinct parts: repositories, branches, and tags.

http://trac.osgeo.org/grass/browser/grass/

1. trunk. contains all source code and history for a project. aka HEAD

for example grass (for grass 5.x), grass6 (grass 6.x),

2. branches. at a certain date it is split off from HEAD. New developement in HEAD will not appear in the branch, changes must be backported to the branch. Usually created in advance of a stable release to separate code that is trying to be stabilized from new development.

for example releasebranch_6_0 or releasebranch_6_2 in the grass6 repository for GRASS 6.0.x and GRASS 6.2.x

3. tag. a branch snapshot, technically an alias to a date stamp in a branch

for example release_20071127_grass_6_2_3 in the releasebranch_6_2 branch for the GRASS 6.2.3 release

4. also the GRASS Web site pages are managed in SVN: http://trac.osgeo.org/grass/browser/grass-web

5. also the GRASS Addons are managed in SVN: http://trac.osgeo.org/grass/browser/grass-addons

Implementation

The general principle is that no new development occurs on a release branch.

Development occurs on a development branch (or the trunk). When it is deemed time for a new series of releases, a the development branch is forked to create a release branch, and a snapshot of the release branch is created to form the first release candidate. Thereafter, the only modifications to the release branch are made by merging specific changes from the development branch to the release branch. The various release candidates and releases are snapshots of the release branch.

This means that changes whose desirability is uncertain can be made to the development branch. If they work out, they get merged onto the release branch. If they don't work out, they simply don't get merged; there is no need to explicitly back them out to obtain a stable version for release.

Tips for everyone

Setting it up (first time)

  • Download latest source code snapshot
wget http://grass.osgeo.org/grass64/source/snapshot/grass-6.4.svn_src_snapshot_${DATE}.tar.gz
  • move it somewhere on your filesystem without spaces or special characters in the path.
mv grass-6.4.svn_src_snapshot_${DATE}.tar.gz /usr/local/src/
  • decomress it
tar xzf grass-6.4.svn_src_snapshot_${DATE}.tar.gz
  • at this stage, you may want to rename the source directory to something shorter
mv grass-6.4.svn_src_snapshot_${DATE}/ grass64svn/
cd grass64svn/
  • update to the latest code
svn update

Updating entire source tree (another time)

For future updates, do:

  • clear away the existing rubble (recommended if lib/gis/ changed)
make distclean
  • update
svn update
  • re run ./configure and make

Updating just one module

Often you are interested in just a single bugfix or updated module. Assuming the change didn't affect libraries or the build system, you can just update and recompile the code in the module's directory.

  • for example, updating just the r.cost module
cd raster/r.cost
svn up
make
(and 'make install' in the main directory if you always install the software)
  • If includes/ or module header files (*.h) have changed, you will have to run
make clean

before "make".

Tips for users wanting to contributing code

Code Standards

See these files in the source code. To keep the GRASS source code manageable, all new code must conform.

  • SUBMITTING
  • SUBMITTING_SCRIPTS
  • SUBMITTING_TCLTK
  • SUBMITTING_PYTHON
  • SUBMITTING_DOCS

Legal issues

Copyright

  • The developer may keep copyright on submitted code
  • You must include copyright and licensing information in the header comments of your code so that others may know how they can use, extend, modify, and redistribute your work.
  • The developer is encouraged to assign co-copyright to the GRASS Development Team. This gives the GRASS project flexibility over the source code, without this the Team must contact all former developers before allowing a license change (eg a legal hole is found in the GPL and the project needs to migrate to a new version) or confirming the original license. In a 20+ year old project, with often only a name and old email to go by, this becomes unworkable.
Example

at the top of a shell script:

#!/bin/sh
############################################################################
#
# MODULE:       v.in.e00
#
# AUTHOR(S):    Markus Neteler, Otto Dassau
#
# PURPOSE:      Import E00 data into a GRASS vector map
#               Imports single and split E00 files (.e00, .e01, .e02 ...)
#
# COPYRIGHT:    (c) 2004, 2005 GRASS Development Team and GDF Hannover bR, http://www.gdf-hannover.de
#
#               This program is free software under the GNU General Public
#               License (>=v2). Read the file COPYING that comes with GRASS
#               for details.
#
#############################################################################

Licensing

  • GRASS uses the GNU General Public License (the GPL).

Due diligence

Code submission method

(Note: this applies to people without SVN write access)

Be sure to develop on top of the LATEST GRASS code (SVN HEAD), not on top of a stable branch.

You can re-check before submission with:

svn diff

Preparing a patch

  • See the wiki page describing Patches.
  • Create a Unidiff patch against the latest development branch SVN (trunk).

Be sure to create them in unified ("diff -u") format. "Plain" diffs (the default format) are risky, because they will apply without warning to code which has been substantially changed; they are also harder to read than unified. The default for 'svn diff' is to create a unidiff.

Such diffs should be made from the top-level directory, e.g. "svn diff display/d.vect/main.c"; that way, the diff will include the pathname rather than just the generic "main.c".

Imagine that You have hacked around in module r.foo. To create a patch you should use following commands:

 cd /path/to/grass7
 svn diff raster/r.foo > r.foo.patch

Applying someone else patch

To apply patch created by someone else using "svn diff" command, You need to use following command:

 cd /path/to/grass7
 patch -p0 < /path/to/r.foo.patch

Creating a GEM package

The GEM system makes it easy to prepare intergrated add-on modules or groups of add-on modules as extensions to the existing GRASS source code. Users do not need to build the entire GRASS source package to add and build GEM packages.

Submitting it to the Wiki Add-Ons page

The Add-ons page contains user contributed code which is not intended to go into the main GRASS source tree or is still experimental

Submitting it to the code tracker

Non-trival formal patches which are expected to become part of the main GRASS source tree should be uploaded to the "code patches" tracker and GRASS's trac site.

Announcing it on the GRASS Development mailing list

Once it is uploaded to the Wiki AddOns page or the trac code tracker, announce it on the GRASS-dev mailing list.

Final products added to the Wiki Add-Ons page should be announced on the GRASS users' mailing list.

Getting help

Tips for GRASS developers

(SVN write access, committing)

Becoming a GRASS developer

The GRASS Project Steering Committee is in charge of giving new developers write access to the CVS. This generally happens after the developer has been submitting code for long enough for the other developers to become familiar with the person and their coding ability.

Read on here: http://trac.osgeo.org/grass/wiki/HowToContribute

Responsibilities

Setting it up

  • Connection to SVN with write access: see here
  • configuring GRASS for code development:
    • Linux: please use these flags to configure GRASS, they will help you to catch most programming problems:
    MYCFLAGS="-g -Wall -Werror-implicit-function-declaration -fno-common"
    MYCXXFLAGS="-g -Wall"
    CFLAGS="$MYCFLAGS" CXXFLAGS="$MYCXXFLAGS" ./configure ... (more flags and parameters)
    • MacOSX:
    • MS-Windows:

Commiting

  • work against latest development SVN HEAD (update before committing)
  • code must compile
  • verify changes with 'svn diff' before all commits
  • cvs commit: make the svn log message a useful synopsis of the change (svn2cl script)
  • double check the change using the live WebSVN interface or grass-qa mailing list