Working with SVN

From GRASS-Wiki
Revision as of 07:17, 13 December 2006 by ⚠️MarisN (talk | contribs)
Jump to navigation Jump to search

[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]

Tips for everyone

  • You can setup default CVS options in a file called .cvsrc in your home directory.
cat << EOF >> ~/.cvsrc
-z3
diff -u
update -dP
EOF

Tips for users

(read-only access to the latest code)

Setting it up (first time)

  • Download latest source code snapshot
wget http://grass.itc.it/grass63/source/snapshot/grass-6.3.cvs_src_snapshot_${DATE}.tar.gz
  • 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/
  • decomress it
tar xzf grass-6.3.cvs_src_snapshot_${DATE}.tar.gz
  • at this stage, you may want to rename the source directory to something shorter
mv grass-6.3.cvs_src_snapshot_${DATE}/ grass63/
cd grass63/
  • set for anonymous connection to CVS server
CVSROOT=:pserver:grass-guest@intevation.de:/home/grass/grassrepository
export CVSROOT
  • login to CVS
cvs login
password: grass
  • update to the latest
cvs -z3 update -dP

Updating entire source tree (second time)

The is no need to login to CVS now, it remembers all that.

  • clear away the existing rubble
make distclean
  • update (You can skip the reporting of all directories by adding the -q flag (assumes -z3 and -dP were added to ~/.cvsrc)
cvs -q 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
cvs up
make
  • 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

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

  • PSC RFC2

Code submission method

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

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

You can re-check before submission with:

cvs diff -u

Preparing a patch

  • create a unidiff patch against the latest development branch CVS

Be sure to create 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.

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 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:

 cd /path/to/grass6
 cvs diff -u raster/r.foo > r.foo.patch

Applying someone else patch

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

 cd /path/to/grass6
 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.

  • link to GEM add-on docs

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 Gforge site.

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

(CVS 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.

Responsibilities

Setting it up

  • 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 branch CVS HEAD (update before committing)
  • code must compile
  • verify changes with 'cvs diff -u' before all commits
  • cvs commit: make the cvs log message a useful synopsis of the change
  • double check the change using the live WebCVS interface or grass-commit mailing list