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

Follow the best writing practices specified by GRASS [wiki:Submitting submitting rules] for a given language. Write tests for your code. Note that framework for testing and rules for testing are under development but you can use the [http://trac.osgeo.org/grass/browser/sandbox/wenzeslaus/gunittest/testing.rst temporary guide] or [source:grass/trunk/general/g.list/test_g_list.py?rev=60619 existing examples].

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