[GRASS-SVN] r29581 - grass/trunk
svn_grass at osgeo.org
svn_grass at osgeo.org
Sun Jan 6 06:42:35 EST 2008
Author: martinl
Date: 2008-01-06 06:42:32 -0500 (Sun, 06 Jan 2008)
New Revision: 29581
Modified:
grass/trunk/SUBMITTING
grass/trunk/SUBMITTING_DOCS
grass/trunk/SUBMITTING_PYTHON
grass/trunk/SUBMITTING_SCRIPTS
grass/trunk/SUBMITTING_TCLTK
Log:
When submitting new files to the repository set SVN properties. Id changed to Date.
Modified: grass/trunk/SUBMITTING
===================================================================
--- grass/trunk/SUBMITTING 2008-01-06 10:03:23 UTC (rev 29580)
+++ grass/trunk/SUBMITTING 2008-01-06 11:42:32 UTC (rev 29581)
@@ -1,4 +1,4 @@
-$Id$
+$Date$
NOTE: Please improve this list!
@@ -34,6 +34,7 @@
In future, there will be a centralized contribution directory.
+
3. Add a header section to each file you submit and make sure you include
the copyright. The purpose section is meant to contain a general
overview of the code in the file to assist other programmers that will
@@ -189,12 +190,14 @@
Could somebody please add others (please verify that they are
useful and safe first)
+
12. Use function names which fulfil the official GNU naming convention.
http://www.gnu.org/prep/standards/html_node/Names.html#Names
Instead of naming a function like: MyNewFunction() use underscores
for seperation and lower case letters: my_new_function().
+
13. Don't use the C++ comment style! This confuses several compilers.
Use instead:
/* C-comments */
@@ -237,6 +240,7 @@
their encapsulated lines from source code (one example was that someone
removed drand48 definition.)
+
17. Suggested compiler flags:
We suggest to use very strict compiler flags to capture errors
at the very beginning. Here our list of flags, please use them
@@ -253,6 +257,7 @@
MS-Windows: [to be suggested]
+
18. Make sure a new line is at the end of each file.
@@ -275,6 +280,7 @@
vector/v.digit/Makefile
If you are unsure, please ask on the GRASS Developers list.
+
20. Have a look at ./INSTALL
@@ -316,6 +322,7 @@
"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.
The first letters for module name should be:
@@ -338,6 +345,7 @@
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
@@ -355,14 +363,31 @@
http://www.grass-gis.org/mailman/listinfo/grass-qa
-29. Tell the other developers about the new code using the following e-mail:
+
+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
+
+
+30. 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
-30. In case of questions feel free to contact the developers at the above
+31. In case of questions feel free to contact the developers at the above
mailing list.
http://www.grass-gis.org/devel/index.php#submission
Modified: grass/trunk/SUBMITTING_DOCS
===================================================================
--- grass/trunk/SUBMITTING_DOCS 2008-01-06 10:03:23 UTC (rev 29580)
+++ grass/trunk/SUBMITTING_DOCS 2008-01-06 11:42:32 UTC (rev 29581)
@@ -1,4 +1,4 @@
-$Id$
+$Date$
NOTE: Please improve this list!
@@ -12,11 +12,13 @@
[ see SUBMITTING_TCLTK for tcl and tk hints ]
[ see SUBMITTING_PYTHON for Python code hints ]
+
1. Editing of HTML pages
To avoid insertion of too complicated HTML tags (see also below),
we strongly suggest to use a plain text editor rather than a
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
@@ -40,6 +42,7 @@
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
no other HTML tags than:
@@ -47,7 +50,19 @@
<H2> <H3> <H4> <HEAD> <HEADER> <HR> <I> <IMG> <LI> <OL> <P>
<PRE> <SUP> <TABLE> <TD> <TH> <TITLE> <TR> <UL>
-See also:
+
+4. When submitting new files to the repository set SVN properties,
+ e.g. for HTML file
+
+ svn:mime-type : text/html
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+5. See also
http://grass.gdf-hannover.de/wiki/Updating_GRASS_Documentation
...
Modified: grass/trunk/SUBMITTING_PYTHON
===================================================================
--- grass/trunk/SUBMITTING_PYTHON 2008-01-06 10:03:23 UTC (rev 29580)
+++ grass/trunk/SUBMITTING_PYTHON 2008-01-06 11:42:32 UTC (rev 29581)
@@ -1,4 +1,4 @@
-$Id:$
+$Date$
NOTE: Please improve this list!
@@ -12,6 +12,7 @@
[ see SUBMITTING_TCLTK for tcl and tk hints ]
[ see SUBMITTING_DOCS for documentation ]
+
1. Indentation
As Python determines nesting based upon indentation, it
@@ -22,6 +23,7 @@
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
@@ -48,18 +50,23 @@
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':
@@ -71,12 +78,29 @@
"svn diff gui/wxpython/wxgui.py"; that way, the diff will
include the pathname rather than just "wxgui.py".
+
+8. When submitting new files to the repository set SVN properties,
+ usually for directory
+
+ svn:ignore : *.pyc
+
+ or e.g. for Python file
+
+ svn:mime-type : text/python
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
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
Modified: grass/trunk/SUBMITTING_SCRIPTS
===================================================================
--- grass/trunk/SUBMITTING_SCRIPTS 2008-01-06 10:03:23 UTC (rev 29580)
+++ grass/trunk/SUBMITTING_SCRIPTS 2008-01-06 11:42:32 UTC (rev 29581)
@@ -1,4 +1,4 @@
-$Id$
+$Date$
NOTE: Please improve this list!
@@ -12,10 +12,12 @@
[ 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.osgeo.org/grass63/manuals/html63_user/g.parser.html
+
1. Use the directory structure to place your script appropriately into
the source tree
- scripts go into scripts/
@@ -25,6 +27,7 @@
Also add a Makefile and a description.html file into this directory.
See existing scripts for examples.
+
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
overview of the code in the file to assist other programmers that will
@@ -57,13 +60,16 @@
Just select an existing module which is close to your application to save
efforts.
+
3. - deleted.
We don't want the $ ID $ in scripts any more as it
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.
+
5. [This rule is currently under review] If you search for a command in $PATH, do NOT
use the "which" command or the "type -p" command. Both commands are not
supported on all platforms, thus causing problems for some people. As an
@@ -97,6 +103,7 @@
fi
</?>
+
6. Add a test to check if the user is in GRASS before starting main part
of script. Result of running the script is unpredicable otherwise.
@@ -108,6 +115,7 @@
This is the only case, where g.message module (see below) can not be used.
In all other cases, you should prefer it's usage over the 'echo' command.
+
7. Create and use secure temporary files and directories. Use the g.tempfile
module to do this. e.g.
@@ -122,6 +130,7 @@
the same name. Beware of commands like "rm -f ${TMP}*" as this becomes
"rm -f *" if $TMP is unset (hence the test above).
+
8. Testing the existence of variables. For portability, use
if [ -z "$VARIABLE" ] ; then
instead of
@@ -165,6 +174,7 @@
... and so forth. See 'g.manual g.findfile' for details.
+
11. For any informational output, use the g.message modul. This module should
be also used for error messages and warnings. You can also use it for
debugging purposes.
@@ -183,8 +193,10 @@
Try to omit any usage of the 'echo' command for informational output.
+
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 SVN).
You can re-check before submission with 'cvs diff':
@@ -197,21 +209,39 @@
"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:
+
+14. For portability, scripts must work on any POSIX compliant shell, and
+ therefore may not include any Bashisms. Test with ash for errors:
+
+ ash -n scriptname
+
+
+15. When submitting new files to the repository set SVN properties,
+ usually for directory
+
+ svn:ignore : *.tmp.html
+
+ or e.g. for script file
+
+ svn:executable : *
+ svn:mime-type : text/x-sh
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
+
+16. 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
-15. In case of questions feel free to contact the developers at the above
+
+17. In case of questions feel free to contact the developers at the above
mailing list.
http://www.grass-gis.org/devel/index.php#submission
-
-16. For portability, scripts must work on any POSIX compliant shell, and
- therefore may not include any Bashisms. Test with ash for errors:
-
- ash -n scriptname
-
...
[please add further hints if required]
Modified: grass/trunk/SUBMITTING_TCLTK
===================================================================
--- grass/trunk/SUBMITTING_TCLTK 2008-01-06 10:03:23 UTC (rev 29580)
+++ grass/trunk/SUBMITTING_TCLTK 2008-01-06 11:42:32 UTC (rev 29581)
@@ -1,4 +1,4 @@
-$Id:$
+$Date$
NOTE: Please improve this list!
@@ -12,12 +12,14 @@
[ 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
- general grass tcl/tk libraries and reusable code go into lib/gtcltk
- user interfaces go in gui/tcltk
- scripts go in scripts/
Programs here must have a proper Makefile and description.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
@@ -42,14 +44,17 @@
The copyright protects your rights according to GNU General Public
License (www.gnu.org).
+
3. 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 need to change or understand your code in the future.
Many of the programmers working on grass are not heavily invested in tcl
and tk, so extra documentation and explanation are greatly appreciated.
+
4. Test your program with both tcl/tk 8.3 and tcl/tk 8.4.
+
5. Always use the gettext macros with [G_msg "..."] for user messages.
The string must be quoted using quotation marks, not braces, for
xgettext to find it. The string cannot include variable ($) or
@@ -66,6 +71,7 @@
format [G_msg "We produced %1\$d units in location %2\$s"] $num $city
format [G_msg "In location %2\$s we produced %1\$d units"] $num $city
+
6. Use "GRASS_TCLSH" and "GRASS_WISH" environment variables instead of
"tclsh" and "wish" at the start of Tcl/Tk scripts. This allows users to
override the default names, so that developers don't need worry about the
@@ -84,6 +90,7 @@
# the next line restarts using wish. Note the backslash: \
exec $GRASS_WISH "$0" "$@"
+
7. Do not source files that have already been sourced.
gui.tcl sources:
@@ -94,12 +101,14 @@
If your code requires something to be sourced before it note so
in a comment at the top of the file.
+
8. Set tabstops in your editor to 8 spaces.
When modifying files use the indentation style that is already present.
Please use consistent indentation style in your new code. Whether you use
tabs or spaces to indent please be consistent. Where tabs and spaces are
mixed please remember that a tab is 8 spaces.
+
9. Use the tk options database to control the appearance of your user interface.
In general do not set options on tk widgets unless that option is truly
specific to that widget. It makes them harder to customize.
@@ -124,12 +133,15 @@
by options.tcl. You can include it at the start of your script with:
source $env(GISBASE)/etc/gtcltk/options.tcl
+
10. Avoid using global variables. Thay are a frequent source of bugs, make code
harder to understand, and make your program difficult to reuse. Additionally,
putting code into procs usually makes it run faster (it gets compiled).
+
11. For consistency, use README rather than README.txt for any README files.
+
12. Use of GRASS commands in shell wrapper.
Any GRASS program run in an xterm (those which do interactive query) needs
@@ -148,6 +160,7 @@
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
SVN repository). You can re-check before submission with 'svn
diff':
@@ -161,16 +174,19 @@
"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://lists.osgeo.org/mailman/listinfo/grass-dev
+
15. In case of questions feel free to contact the developers at the above
mailing list.
http://www.grass-gis.org/devel/index.php#submission
+
16. Try to evaluate things only once. Tcl compiles the program to bytecode which
can be interpreted fairly quickly. If there are strings that must still be
evaluated tcl must parse and either compile or interpret them
@@ -201,6 +217,7 @@
multiple times store it in a variable that will not be destroyed or
changed between reuse. Tcl stores the compiled regex with the variable.
+
17. You might want to decompose lists in a somewhat easy way:
Difficult and slow:
@@ -217,6 +234,7 @@
Be sure to include a comment as to what you are doing.
+
18. Use the Tcl list functions (list, lappend etc) for manipulating lists.
For example, use:
@@ -239,6 +257,7 @@
Overlooking either of these points is likely to result in code which
fails when a command argument contains a space.
+
19. Tcl C library:
Memory allocated with Tcl_Alloc (such as the result of Tcl_Merge)
must be freed with Tcl_Free. This means that the ->freeProc of
@@ -246,5 +265,17 @@
TCL_DYNAMIC. Incorrectly freeing memory with glibc free will
cause segfaults in Tcl 8.4 and later.
+
+20. When submitting new files to the repository set SVN properties,
+ e.g.
+
+ svn:executable : *
+ svn:mime-type : text/x-tcl
+ svn:keywords : Author Date Id
+ svn:eol-style : native
+
+ See
+ http://svnbook.red-bean.com/en/1.4/svn.advanced.props.html
+
...
[please add further hints if required]
More information about the grass-commit
mailing list