[[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`.

=== Commit messages ===

Generally, the commit message (log message) should give an information about ''what changed in the code'' and ''how the change affects the functionality''. Additionally, the change of dependencies and changes of functionality of depended code should be discussed if applicable.

The general format of a message is:

{{{
module or library: description (possible Trac ticket, merge commit or related commit)
}}}

Examples (of single line commit messages):

{{{
r.to.vect: corrected x in the crowded message
g.mremove: Changed the interface to that of g.mlist and added exclude= (ticket #2228)
libraster: Added raster name and row info to get/put_row error messages
vlib/pg: column check must be case-insensitive 
wxGUI/lmgr: add measuring of distances also to Layer Manager
wxGUI: workaround for not visible toolbars on Mac with wxPython 3
}}}

Include ticket using hash mark and ticket number, e.g. `#2228`, and another commit (revision) using letter r and revision number, e.g. `r60975`. This will allow Trac (and perhaps other systems) to create a link to the ticket or commit (or revision). However, do not rely on this and always include the information about what and why the commit is changing and how (consider browsing commit messages in command line). 

It is possible and allowed to do multiline commit messages but you should consider the following. First, multiline commit messages should be used to provide further details about the commit. They should not be used to describe large changes of code. Instead, these large changes should be split into the separate commits with shorted commit messages. Note that this not only simplifies writing of good, simple and readable commit messages but it also makes code review and regression testing easier. Second, if you have a lot to say about the commit you should perhaps include this in the comments or documentation (you can refer there to tickets or other commits too in the same way as in commit messages, although they will not be automatically linked).

Write the commit messages in the way that they can be used to create/update change logs, wiki:Release pages and news in general.

Don't include your name (or id) to commit message, this is stored separately and automatically. However, if you are committing someone's code (e.g. path) or you are writing the code together with someone, include his or her name.

Include the module, library or component name as a prefix separated by colon, e.g. `libraster:`. You don't have to include file names in the commit message, they are managed by SVN itself.

If you are not sure if your style is correct, ask on mailing list.

Some bad examples (of single line commit messages):
{{{
r.slope.aspect: fix compilation
(missing information what exactly was broken and reasoning behind the fix; it's clear that we are not trying to break something by the commit)

wxGUI/render: attempt to fix #560
(missing information what is #560 and how we are trying to fix it)

Add tests for Table and Columns classes
(we don't know where the classes belongs to, prefix pygrass: or pythonlib/pygrass would tell us in this case)

fix bug introduced in r60216
(missing information how the bug was fixed and which bug it was)

fix r60216 (i18n)
(it should probably say something like: wxGUI: fix insufficient handling of i18n (introduced in r60216))

libraster:Added raster name and row info to get/put_row error messages
(missing space after colon)
}}}


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