Changes between Initial Version and Version 1 of Submitting/General

Timestamp:

Jun 21, 2014, 4:49:18 AM (10 years ago)

Author:

martinl

Comment:

--

Submitting/General

@@ +1 @@
+''Please improve this list...''
+
+Dear (new) GRASS developer,
+
+4.  We don't want the `$ID$` in source code any more as it causes problems
+for the SVN branches.
+
+
+14. 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.
+
+
+18. Make sure a new line is at the end of each file and UNIX style newlines are used (`\n`).
+
+
+19. 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.
+
+    
+20. Have a look at source:grass/trunk/INSTALL
+
+
+24. For consistency, use `README` rather than `README.txt` for any `README` files.
+
+
+25. 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
+
+26. 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`.
+
+
+27. 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`    
+
+
+28. 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
+
+
+29. 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.
+
+
+31. 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'.
+
+
+32. 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
+
+
+33. In case of questions feel free to contact the developers at the above mailing list.[[BR]]
+    http://grass.osgeo.org/development/
+
+...
+
+''[please add further hints if required]'''
+
+''Your attention to detail is appreciated.''