[[TOC]]
= Submitting General Notes =

== Submitting code to SVN ==

Be sure to develop on top of the LATEST GRASS code (which is in our SVN repository). You can re-check before submission with `svn diff`:

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. `svn diff display/d.vect/main.c`; that way, the diff will include the pathname rather than just an ambiguous `main.c`.

=== SVN Properties ===

When submitting new files to the repository set SVN properties,
    usually for directory
{{{
      svn:ignore : *.tmp.html
      		   *OBJ*
}}}
    or e.g. for C-file
{{{    
      svn:mime-type : text/x-csrc
      svn:keywords : Author Date Id
      svn:eol-style : native
}}}
    See
    http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html

    To set a property:
{{{
      svn propset svn:keywords 'Author Date Id' <file>
      svn propset svn:mime-type text/x-sh grass_shellscript.sh
}}}
    To edit the `svn:ignore` property using your default text editor:
{{{
      svn propedit svn:ignore <directory>
}}}
    To set the `svn:ignore` property non-interactively, first create a file containing the value:
{{{
      echo "*.tmp.html" > ignore.txt
      echo "*OBJ*" >> ignore.txt
}}}
    then use:
{{{
      svn propset -F ignore.txt svn:ignore <directory>
}}}
    List of mime-type:
{{{
      C++ files (.cpp): text/x-c++src
      C files (.c): text/x-csrc
      DTD files (.dtd): text/xml-dtd
      GIF files (.gif): image/gif
      Header files (.h): text/x-chdr
      HTML files (.html): text/html
      JPEG files (.jpg): image/jpeg
      Makefiles: text/x-makefile
      PNG files (.png): image/png
      Python files (.py): text/x-python
      Shell scripts (.sh): text/x-sh
      Text files (.txt): text/plain
      XML files (.xml): text/xml
}}} 
      (please update the list...)

    For your convenience use the source:grass-addons/tools/module_svn_propset.sh script.

=== SVN Property Id ===

We don't want the `$ID$` in source code any more as it causes problems
for the SVN branches.

=== Comments ===

PLEASE take the time to add comments throughout your code explaining what the code is doing. It will save a HUGE amount of time and frustration for other programmers that may have to change your code in the future.

=== End Of Line ===

Make sure a new line is at the end of each file and UNIX style newlines are used (`\n`).

== Makefiles ==

When writing Makefiles, use the current standard.

    If you have to use commands, please check for:
{{{    
            avoid     | use instead
    ------------------+---------------
    make target       | $(MAKE) target
    mkdir target      | $(MKDIR) target
    cp  (executable)  | $(INSTALL) -m 755 file target
    cp  (normal file) | $(INSTALL) -m 644 file target
    ar                | $(AR)
}}}
    `rm`: be VERY careful with recursive remove. Also beware of
    removing $(FOO)* if $(FOO) has any chance of being empty.

    Examples: see below examples or others[[BR]]
              source:grass/trunk/raster/r.info/Makefile [[BR]]
              source:grass/trunk/vector/v.edit/Makefile

    If you are unsure, please ask on the GRASS Developers list.

=== !AutoConf ===

If you need to add support for a different library in the 'configure' script, you should first seek consent in the grass-dev mailing list (see below), then you need to expand 'configure.in' and run subsequently `autoconf-2.13` (later versions will not work) to re-generate 'configure'.

== Naming Convetions ==
    
Have a look at source:grass/trunk/INSTALL

For consistency, use `README` rather than `README.txt` for any `README` files.

=== Variables ===

GRASS/Environment variables:
   If you add a new variable, please follow the naming convention. All variables are described in source:grass/trunk/lib/init/variables.html

=== Modules ===

Try to use module names which describe shortly the intended purpose of the module.

    The first letters for module name should be:
{{{
	d. 	- display commands
	db. 	- database commands
	g. 	- general GIS management commands
	i. 	- imagery commands
	m.	- miscellaneous tool commands
	ps. 	- postscript commands
	r. 	- raster commands
	r3. 	- raster3D commands
	v. 	- vector commands
}}}
    Some additional naming conventions
    * export modules:     (type).out.(format) eg: `r.out.arc`, `v.out.ascii`
    * import module:      (type).in.(format)  eg: `r.in.arc`, `v.in.ascii`
    * conversion modules: (type).to.(type)    eg: `r.to.vect`, `v.to.rast`, `r3.to.rast`

    Avoid module names with more than two dots in the name. 
    Example: instead of `r.to.rast3.elev` use `r.to.rast3elev`    

== Code Quality ==

Use the grass test suite to test your modules.

    http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite

    You can easily write specific tests for your modules.

    If your module is part of GRASS and you created some standard test cases, please contact the developers to add your tests to the default test suite.  This will automatize complex test scenarios and assure to find bugs much faster, if changes were made to your modules or to the grass library.

    Consider to subscribe to the GRASS Quality Assessment System to get immediate notification about the code quality:

    http://lists.osgeo.org/mailman/listinfo/grass-qa

== Contact us ==

Tell the other developers about the new code using the following e-mail:
    grass-dev@lists.osgeo.org
 
    To subscribe to this mailing list, see
    http://lists.osgeo.org/mailman/listinfo/grass-dev


In case of questions feel free to contact the developers at the above mailing list.[[BR]]
    http://grass.osgeo.org/development/