Changes between Version 2 and Version 3 of Submitting/General


Ignore:
Timestamp:
06/21/14 04:56:23 (11 years ago)
Author:
martinl
Comment:

--

Legend:

Unmodified
Added
Removed
Modified

  • Submitting/General

    v2 v3  
    1 ''Please improve this list...''
     1= Submitting General Notes =
    22
    3 Dear (new) GRASS developer,
     3== Submitting code to SVN ==
    44
    5 1.  We don't want the `$ID$` in source code any more as it causes problems
    6 for the SVN branches.
     5Be 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`:
    76
     7Be 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.
    88
    9 1. 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.
     9Such 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`.
    1010
     11=== SVN Properties ===
    1112
    12 18. Make sure a new line is at the end of each file and UNIX style newlines are used (`\n`).
    13 
    14 
    15 19. When writing Makefiles, use the current standard.
    16 
    17     If you have to use commands, please check for:
    18 {{{   
    19             avoid     | use instead
    20     ------------------+---------------
    21     make target       | $(MAKE) target
    22     mkdir target      | $(MKDIR) target
    23     cp  (executable)  | $(INSTALL) -m 755 file target
    24     cp  (normal file) | $(INSTALL) -m 644 file target
    25     ar                | $(AR)
    26 }}}
    27     `rm`: be VERY careful with recursive remove. Also beware of
    28     removing $(FOO)* if $(FOO) has any chance of being empty.
    29 
    30     Examples: see below examples or others[[BR]]
    31               source:grass/trunk/raster/r.info/Makefile [[BR]]
    32               source:grass/trunk/vector/v.edit/Makefile
    33 
    34     If you are unsure, please ask on the GRASS Developers list.
    35 
    36    
    37 20. Have a look at source:grass/trunk/INSTALL
    38 
    39 
    40 24. For consistency, use `README` rather than `README.txt` for any `README` files.
    41 
    42 
    43 25. GRASS/Environment variables:
    44    If you add a new variable, please follow the naming convention. All variables are described in source:grass/trunk/lib/init/variables.html
    45 
    46 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`:
    47 
    48     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.
    49 
    50     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`.
    51 
    52 
    53 27. Try to use module names which describe shortly the intended purpose of the module.
    54 
    55     The first letters for module name should be:
    56 {{{
    57         d.      - display commands
    58         db.     - database commands
    59         g.      - general GIS management commands
    60         i.      - imagery commands
    61         m.      - miscellaneous tool commands
    62         ps.     - postscript commands
    63         r.      - raster commands
    64         r3.     - raster3D commands
    65         v.      - vector commands
    66 }}}
    67     Some additional naming conventions
    68     * export modules:     (type).out.(format) eg: `r.out.arc`, `v.out.ascii`
    69     * import module:      (type).in.(format)  eg: `r.in.arc`, `v.in.ascii`
    70     * conversion modules: (type).to.(type)    eg: `r.to.vect`, `v.to.rast`, `r3.to.rast`
    71 
    72     Avoid module names with more than two dots in the name.
    73     Example: instead of `r.to.rast3.elev` use `r.to.rast3elev`   
    74 
    75 
    76 28. Use the grass test suite to test your modules.
    77 
    78     http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite
    79 
    80     You can easily write specific tests for your modules.
    81 
    82     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.
    83 
    84     Consider to subscribe to the GRASS Quality Assessment System to get immediate notification about the code quality:
    85 
    86     http://lists.osgeo.org/mailman/listinfo/grass-qa
    87 
    88 
    89 29. When submitting new files to the repository set SVN properties,
     13When submitting new files to the repository set SVN properties,
    9014    usually for directory
    9115{{{
    … …  
    14064    For your convenience use the source:grass-addons/tools/module_svn_propset.sh script.
    14165
     66=== SVN Property Id ===
    14267
    143 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'.
     68We don't want the `$ID$` in source code any more as it causes problems
     69for the SVN branches.
    14470
     71=== Comments ===
    14572
    146 32. Tell the other developers about the new code using the following e-mail:
     73PLEASE 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.
     74
     75=== End Of Line ===
     76
     77Make sure a new line is at the end of each file and UNIX style newlines are used (`\n`).
     78
     79== Makefiles ==
     80
     81When writing Makefiles, use the current standard.
     82
     83    If you have to use commands, please check for:
     84{{{   
     85            avoid     | use instead
     86    ------------------+---------------
     87    make target       | $(MAKE) target
     88    mkdir target      | $(MKDIR) target
     89    cp  (executable)  | $(INSTALL) -m 755 file target
     90    cp  (normal file) | $(INSTALL) -m 644 file target
     91    ar                | $(AR)
     92}}}
     93    `rm`: be VERY careful with recursive remove. Also beware of
     94    removing $(FOO)* if $(FOO) has any chance of being empty.
     95
     96    Examples: see below examples or others[[BR]]
     97              source:grass/trunk/raster/r.info/Makefile [[BR]]
     98              source:grass/trunk/vector/v.edit/Makefile
     99
     100    If you are unsure, please ask on the GRASS Developers list.
     101
     102=== AutoConf ===
     103
     104If 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'.
     105
     106== Naming Convetions ==
     107   
     108Have a look at source:grass/trunk/INSTALL
     109
     110For consistency, use `README` rather than `README.txt` for any `README` files.
     111
     112=== Variables ===
     113
     114GRASS/Environment variables:
     115   If you add a new variable, please follow the naming convention. All variables are described in source:grass/trunk/lib/init/variables.html
     116
     117=== Modules ===
     118
     119Try to use module names which describe shortly the intended purpose of the module.
     120
     121    The first letters for module name should be:
     122{{{
     123        d.      - display commands
     124        db.     - database commands
     125        g.      - general GIS management commands
     126        i.      - imagery commands
     127        m.      - miscellaneous tool commands
     128        ps.     - postscript commands
     129        r.      - raster commands
     130        r3.     - raster3D commands
     131        v.      - vector commands
     132}}}
     133    Some additional naming conventions
     134    * export modules:     (type).out.(format) eg: `r.out.arc`, `v.out.ascii`
     135    * import module:      (type).in.(format)  eg: `r.in.arc`, `v.in.ascii`
     136    * conversion modules: (type).to.(type)    eg: `r.to.vect`, `v.to.rast`, `r3.to.rast`
     137
     138    Avoid module names with more than two dots in the name.
     139    Example: instead of `r.to.rast3.elev` use `r.to.rast3elev`   
     140
     141== Code Quality ==
     142
     143Use the grass test suite to test your modules.
     144
     145    http://www-pool.math.tu-berlin.de/~soeren/grass/GRASS_TestSuite
     146
     147    You can easily write specific tests for your modules.
     148
     149    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.
     150
     151    Consider to subscribe to the GRASS Quality Assessment System to get immediate notification about the code quality:
     152
     153    http://lists.osgeo.org/mailman/listinfo/grass-qa
     154
     155== Contact us ==
     156
     157Tell the other developers about the new code using the following e-mail:
    147158    grass-dev@lists.osgeo.org
    148159 
    … …  
    151162
    152163
    153 33. In case of questions feel free to contact the developers at the above mailing list.[[BR]]
     164In case of questions feel free to contact the developers at the above mailing list.[[BR]]
    154165    http://grass.osgeo.org/development/
    155 
    156 ...
    157 
    158 ''[please add further hints if required]'''
    159 
    160 ''Your attention to detail is appreciated.''