[GRASS-SVN] r29431 - grass/trunk
svn_grass at osgeo.org
svn_grass at osgeo.org
Thu Dec 13 16:04:23 EST 2007
Author: martinl
Date: 2007-12-13 16:04:23 -0500 (Thu, 13 Dec 2007)
New Revision: 29431
Added:
grass/trunk/SUBMITTING_PYTHON
Modified:
grass/trunk/SUBMITTING
grass/trunk/SUBMITTING_DOCS
grass/trunk/SUBMITTING_SCRIPTS
grass/trunk/SUBMITTING_TCLTK
Log:
Add submitting instructions for Python code (need to be improved...)
Fix other submitting files (cvs->svn)
Modified: grass/trunk/SUBMITTING
===================================================================
--- grass/trunk/SUBMITTING 2007-12-13 15:43:18 UTC (rev 29430)
+++ grass/trunk/SUBMITTING 2007-12-13 21:04:23 UTC (rev 29431)
@@ -4,16 +4,17 @@
Dear (new) GRASS Developer,
-When submitting C code to GRASS CVS repository, please take
-care of following rules:
+When submitting C code to GRASS SVN repository, please take care of
+following rules:
[ see SUBMITTING_SCRIPTS for shell script hints ]
[ see SUBMITTING_TCLTK for tcl and tk hints ]
[ see SUBMITTING_DOCS for documentation ]
+[ see SUBMITTING_PYTHON for Python code hints ]
1. Get and read the GRASS 6 Programmer's Manual here:
- http://www.grass-gis.org/devel/index.php#prog
+ http://download.osgeo.org/grass/grass6_progman/
or generate it from this source code (the programmer's manual is
integrated in the source code in doxygen style):
@@ -66,7 +67,7 @@
4. - deleted.
We don't want the $ ID $ in source code any more as it causes problems
- for the CVS branches.
+ for the SVN branches.
5. To ensure that the software system continues to work, please include
@@ -74,10 +75,10 @@
#include <grass/config.h>
in your files and make use of the various system dependencies
- contained therein. As one example of this, see
- lib/gmath/fft.c . Please refrain from declaring
- system functions within the software; include the proper header files
- (conditionally dependent on config.h macros if necessary) instead.
+ contained therein. As one example of this, see lib/gmath/fft.c.
+ Please refrain from declaring system functions within the
+ software; include the proper header files (conditionally dependent
+ on config.h macros if necessary) instead.
6. Order of include headers
@@ -86,7 +87,7 @@
1. Core system headers (stdio.h, ctype.h, ...)
2. Headers for non-core system components (X11, libraries).
- 3. Headers for core systems of the package being compiled (grass/gis.h, grass/glocale.h ...)
+ 3. Headers for core systems of the package being compiled (grass/gis.h, grass/glocale.h, ...)
4. Headers for the specific library/program being compiled (geodesic.h, ...)
Each class of header has an obligation to be compatible with those
@@ -126,7 +127,7 @@
exit (EXIT_FAILURE);
...
- exit (EXIT_SUCCESS)
+ exit (EXIT_SUCCESS);
}
@@ -141,7 +142,7 @@
Always use the gettext macros with _("") for user messages,
example:
- G_fatal_error ( _("Vector file [%s] not available"), name);
+ G_fatal_error (_("Vector map <%s> not found"), name);
Pipe/file data output:
@@ -154,8 +155,8 @@
fflush(stdout) always required when using fprintf(stdout, ...).
-10. Use the GRASS library function G_asprintf() instead of the
- standard C functions asprintf(), vsnprintf() and snprintf(). These
+10. Use the GRASS library function G_asprintf() instead of the
+ standard C functions asprintf(), vsnprintf() and snprintf(). These
functions are not portable or have other issues. Example:
char *msg;
@@ -169,9 +170,9 @@
11. Use the following GRASS library functions instead of the standard C
functions. The reason for this is that the following functions ensure
- good programming practice (eg always checking if memory was allocated)
+ good programming practice (e.g. always checking if memory was allocated)
and/or improves portability. PLEASE refer to the programmers manual
- for the proper use (eg determining if any casts are needed for arguments
+ for the proper use (e.g. determining if any casts are needed for arguments
or return values) of these library functions. They may perform a task
slightly different from their corresponding C library function, and thus,
their use may not be the same.
@@ -227,7 +228,7 @@
will make "diff" comparisons with older versions impossible. If indent is
needed, do not check in any changes other than the indentation in the same
commit! Do add the indent switches and any indent warning messages to the
- CVS log. Any change or fix mixed in with an indent is very hard to track
+ SVN log. Any change or fix mixed in with an indent is very hard to track
making it hard for others to follow the change or fix any new bugs.
@@ -274,12 +275,12 @@
vector/v.digit/Makefile
If you are unsure, please ask on the GRASS Developers list.
-
+
20. Have a look at ./INSTALL
21. Have a function included in your module which writes to the history
- file of the map (e.g. command line, parameters etc.). See eg
+ file of the map (e.g. command line, parameters etc.). See e.g.
raster/r.patch/main.c
(the same applies to vector and g3d modules!)
@@ -304,15 +305,15 @@
lib/init/variables.html
-26. Be sure to develop on top of the LATEST GRASS code (which is in CVS).
- You can re-check before submission with 'cvs diff':
+26. Be sure to develop on top of the LATEST GRASS code (which is in 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.
- "cvs diff -u display/d.vect/main.c"; that way, the diff will
+ "svn diff display/d.vect/main.c"; that way, the diff will
include the pathname rather than just "main.c".
27. Try to use module names which describe shortly the intended purpose of the module.
@@ -343,10 +344,11 @@
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.
+ 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:
@@ -357,7 +359,7 @@
grass-dev at lists.osgeo.org
To subscribe to this mailing list, see
- http://www.grass-gis.org/devel/index.php
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
30. In case of questions feel free to contact the developers at the above
@@ -366,4 +368,3 @@
...
[please add further hints if required]
-
Modified: grass/trunk/SUBMITTING_DOCS
===================================================================
--- grass/trunk/SUBMITTING_DOCS 2007-12-13 15:43:18 UTC (rev 29430)
+++ grass/trunk/SUBMITTING_DOCS 2007-12-13 21:04:23 UTC (rev 29431)
@@ -4,12 +4,13 @@
Dear (new) GRASS Developer,
-When submitting documentation to GRASS CVS repository, please take
+When submitting documentation to GRASS SVN repository, please take
care of following rules:
+[ see SUBMITTING for C hints ]
[ see SUBMITTING_SCRIPTS for shell script hints ]
[ see SUBMITTING_TCLTK for tcl and tk hints ]
-[ see SUBMITTING for C hints ]
+[ see SUBMITTING_PYTHON for Python code hints ]
1. Editing of HTML pages
To avoid insertion of too complicated HTML tags (see also below),
@@ -17,26 +18,27 @@
HTML editor for editing.
2. Module manual page:
- Place the documentation in HTML format into 'description.html'.
- The easiest way to do this is to study an existing HTML page
- (to get the page style, e.g. vector/v.to.db/description.html).
- With a few exceptions header and footer are NOT allowed.
- You can add figures (PNG format), the figure name prefix should be the
- module name. See raster/r.terraflow/description.html for an example.
+ Place the documentation in HTML format into 'description.html'.
+ The easiest way to do this is to study an existing HTML page
+ (to get the page style, e.g. vector/v.to.db/description.html).
+ With a few exceptions header and footer are NOT allowed.
+ You can add figures (PNG format), the figure name prefix should be the
+ module name. See raster/r.terraflow/description.html for an example.
- Note that the parameter information is auto-generated upon
- compilation. This is done by running module in a virtual session
- after compilation (see the output of 'make'). To subsequently
- verify the final HTML page, check the resulting HTML pages which
- will be stored with the name of the module.
+ Note that the parameter information is auto-generated upon
+ compilation. This is done by running module in a virtual session
+ after compilation (see the output of 'make'). To subsequently
+ verify the final HTML page, check the resulting HTML pages which
+ will be stored with the name of the module.
- Examples (please add some) should be coded like this:
+ Examples (please add some) should be coded like this:
- <div class="code"><pre>
- v.to.db map=soils type=area option=area col=area_size unit=h
- </pre></div>
+ <div class="code"><pre>
+ v.to.db map=soils type=area option=area col=area_size unit=h
+ </pre></div>
- The online WWW man pages is updated every Saturday by CVS.
+ The online WWW man pages is updated every Saturday (from SVN
+ repository).
3. Usage of limited HTML tags
Since the MAN conversion of g.html2man is limited, please use
@@ -50,4 +52,3 @@
...
[please add further hints if required]
-
Added: grass/trunk/SUBMITTING_PYTHON
===================================================================
--- grass/trunk/SUBMITTING_PYTHON (rev 0)
+++ grass/trunk/SUBMITTING_PYTHON 2007-12-13 21:04:23 UTC (rev 29431)
@@ -0,0 +1,85 @@
+$Id:$
+
+NOTE: Please improve this list!
+
+Dear (new) GRASS Developer,
+
+When submitting Python code to GRASS SVN repository, please take
+care of following rules:
+
+[ see SUBMITTING for C hints ]
+[ see SUBMITTING_SCRIPTS for shell script hints ]
+[ see SUBMITTING_TCLTK for tcl and tk hints ]
+[ see SUBMITTING_DOCS for documentation ]
+
+1. Indentation
+
+ As Python determines nesting based upon indentation, it
+ isn't just a stylistic issue.
+
+ Please use 4-space indentation (GNU Emacs python-mode default).
+
+ See also "Python Style Guide" by Guido van Rossum
+ http://www.python.org/doc/essays/styleguide.html
+
+2. Add a header section to the script you submit and make sure you
+ include the copyright. The purpose section is meant to contain a
+ general over view of the code in the file to assist other
+ programmers that will need to make changes to your code. For this
+ purpose use Python Docstring, see
+ http://epydoc.sourceforge.net/docstrings.html
+
+ Example (fictitious header for a script called r.myscript):
+
+"""
+MODULE: r.myscript
+
+AUTHOR(S): Me <email AT some domain>
+
+PURPOSE: Calculates univariate statistics from a GRASS raster map
+
+COPYRIGHT: (C) 2007 by the GRASS Development Team
+
+ This program is free software under the GNU General Public
+ License (>=v2). Read the file COPYING that comes with GRASS
+ for details.
+"""
+
+ The copyright protects your rights according to GNU General Public
+ License (www.gnu.org).
+
+3. - deleted.
+ We don't want the $ ID $ in source code any more as it causes problems
+ for the branches.
+
+4. 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.
+
+5. Make sure a new line is at the end of each file.
+
+6. For consistency, use README rather than README.txt for any README files.
+
+7. Be sure to develop on top of the LATEST GRASS code (which is in 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 gui/wxpython/wxgui.py"; that way, the diff will
+ include the pathname rather than just "wxgui.py".
+
+8. Tell the other developers about the new code using the following e-mail:
+ grass-dev at lists.osgeo.org
+
+ To subscribe to this mailing list, see
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
+
+9. In case of questions feel free to contact the developers at the above
+ mailing list.
+ http://www.grass-gis.org/devel/index.php#submission
+
+...
+[please add further hints if required]
Property changes on: grass/trunk/SUBMITTING_PYTHON
___________________________________________________________________
Name: svn:mime-type
+ text/plain
Name: svn:keywords
+ Author Date Id
Name: svn:eol-style
+ native
Modified: grass/trunk/SUBMITTING_SCRIPTS
===================================================================
--- grass/trunk/SUBMITTING_SCRIPTS 2007-12-13 15:43:18 UTC (rev 29430)
+++ grass/trunk/SUBMITTING_SCRIPTS 2007-12-13 21:04:23 UTC (rev 29431)
@@ -4,16 +4,17 @@
Dear (new) GRASS Developer,
-When submitting SHELL SCRIPTS to GRASS CVS repositiory,
+When submitting SHELL scripts to GRASS SVN repositiory,
please take care of following rules:
[ see SUBMITTING for C code hints ]
[ see SUBMITTING_TCLTK for tcl and tk hints ]
[ see SUBMITTING_DOCS for documentation ]
+[ see SUBMITTING_PYTHON for Python code hints ]
0. Instructions for the GRASS script parser can be found in the g.parser
module's help page.
- http://grass.ibiblio.org/grass63/manuals/html63_user/g.parser.html
+ http://grass.osgeo.org/grass63/manuals/html63_user/g.parser.html
1. Use the directory structure to place your script appropriately into
the source tree
@@ -58,7 +59,7 @@
3. - deleted.
We don't want the $ ID $ in scripts any more as it
- causes problems for the CVS branches.
+ causes problems for the SVN branches.
4. As a general principle, shell variables should almost always be quoted.
Use only secure temp files, see g.tempfile and scripts/* for examples.
@@ -151,14 +152,14 @@
# test for input raster map
g.findfile element=cell file="$INPUT" > /dev/null
if [ $? -eq 0 ] ; then
- g.message -e "Raster map '$GIS_OPT_MAP' not found in mapset search path"
+ g.message -e "Raster map <$GIS_OPT_MAP> not found in mapset search path"
exit 1
fi
# test for input vector map
eval `g.findfile element=vector file=$GIS_OPT_MAP`
if [ ! "$file" ] ; then
- g.message -e "Vector map '$GIS_OPT_MAP' not found in mapset search path"
+ g.message -e "Vector map <$GIS_OPT_MAP> not found in mapset search path"
exit 1
fi
@@ -169,7 +170,7 @@
debugging purposes.
#normal message:
- g.message "Done."
+ g.message "Done"
# warning:
g.message -w "No input values found, using default values"
@@ -184,7 +185,7 @@
12. For consistency, use README rather than README.txt for any README files.
-13. Be sure to develop on top of the LATEST GRASS code (which is in CVS).
+13. Be sure to develop on top of the LATEST GRASS code (which is in SVN).
You can re-check before submission with 'cvs diff':
Be sure to create unified ("diff -u") format. "Plain"
@@ -193,14 +194,14 @@
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
+ "cvs diff display/d.vect/main.c"; that way, the diff will
include the pathname rather than just "main.c".
14. Tell the other developers about the new code using the following e-mail:
grass-dev at lists.osgeo.org
To subscribe to this mailing list, see
- http://www.grass-gis.org/devel/index.php
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
15. In case of questions feel free to contact the developers at the above
mailing list.
Modified: grass/trunk/SUBMITTING_TCLTK
===================================================================
--- grass/trunk/SUBMITTING_TCLTK 2007-12-13 15:43:18 UTC (rev 29430)
+++ grass/trunk/SUBMITTING_TCLTK 2007-12-13 21:04:23 UTC (rev 29431)
@@ -1,3 +1,5 @@
+$Id:$
+
NOTE: Please improve this list!
Dear (new) GRASS Developer,
@@ -2,3 +4,3 @@
-When submitting TCL and TK SCRIPTS and C code to GRASS CVS repository,
+When submitting TCL and TK SCRIPTS to GRASS SVN repository,
please take care of following rules:
@@ -8,6 +10,7 @@
[ see SUBMITTING for C code hints ]
[ see SUBMITTING_SCRIPTS for shell script hints ]
[ see SUBMITTING_DOCS for documentation ]
+[ see SUBMITTING_PYTHON for Python code hints ]
1. Use the directory structure to place your program appropriately into
the source tree
@@ -145,8 +148,9 @@
be annoying in normal use. Alternatively, redirect stdout/stderr to a
file, to catch any error messages.
-13. Be sure to develop on top of the LATEST GRASS code (which is in CVS).
- You can re-check before submission with 'cvs diff':
+13. Be sure to develop on top of the LATEST GRASS code (which is in
+ 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
@@ -154,14 +158,14 @@
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
+ "cvs diff display/d.vect/main.c"; that way, the diff will
include the pathname rather than just "main.c".
14. Tell the other developers about the new code using the following e-mail:
grass-dev at lists.osgeo.org
To subscribe to this mailing list, see
- http://www.grass-gis.org/devel/index.php
+ http://lists.osgeo.org/mailman/listinfo/grass-dev
15. In case of questions feel free to contact the developers at the above
mailing list.
More information about the grass-commit
mailing list