[mapserver-commits] r8141 - in trunk/docs: . development/rfc
svn at osgeo.org
svn at osgeo.org
Sun Nov 30 14:03:48 EST 2008
Author: hobu
Date: 2008-11-30 14:03:47 -0500 (Sun, 30 Nov 2008)
New Revision: 8141
Modified:
trunk/docs/development/rfc/ms-rfc-1.txt
trunk/docs/development/rfc/ms-rfc-10.txt
trunk/docs/development/rfc/ms-rfc-12.txt
trunk/docs/msdocs_style.txt
Log:
ReST formatting, break at 80, and linkages
Modified: trunk/docs/development/rfc/ms-rfc-1.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-1.txt 2008-11-30 18:56:21 UTC (rev 8140)
+++ trunk/docs/development/rfc/ms-rfc-1.txt 2008-11-30 19:03:47 UTC (rev 8141)
@@ -1,3 +1,5 @@
+.. _rfc1:
+
====================================================
MS RFC 1: Technical Steering Committee Guidelines
====================================================
Modified: trunk/docs/development/rfc/ms-rfc-10.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-10.txt 2008-11-30 18:56:21 UTC (rev 8140)
+++ trunk/docs/development/rfc/ms-rfc-10.txt 2008-11-30 19:03:47 UTC (rev 8141)
@@ -16,7 +16,7 @@
Abstract
--------
-The Open Source Geospatial Foundation (OSGeo) presents a unique opportunity
+The Open Source Geospatial Foundation (`OSGeo`_) presents a unique opportunity
for MapServer in that it can provide an umbrella organization that can
provide benefits and possibilities that a project by itself simply cannot
provide. This RFC will outline what those benefits can be to the project,
@@ -95,19 +95,21 @@
As MapServer joins the foundation some changes are anticipated in the project.
There will need to be a copyright review of the existing code base, ensuring
-that it is all legimately contributed under the existing license. All
-MapServer committers wll need to sign some sort of committer agreement
+that it is all legitimately contributed under the existing license. All
+MapServer committers will need to sign some sort of committer agreement
providing assurance they are not adding encumbered code. MapServer may have
to consider moving its project infrastructure (CVS, website, lists, etc.)
to the foundation at some point. We will also need to establish a MapServer
Project Committee within the foundation. This may just be the MTSC or it
may be broader, including other stakeholders.
-For the time being the MTSC will continue to operate under `MS RFC 1`_ if
+For the time being the MTSC will continue to operate under :ref:`rfc1` if
the motion to join OSGeo is passed. Additional RFC(s) will address any
changes in process deemed necessary as a result of joining the foundation.
Voting history
--------------
-Passed +7. February 6th, 2005.
\ No newline at end of file
+Passed +7. February 6th, 2005.
+
+.. _OSGeo: http://www.osgeo.org
\ No newline at end of file
Modified: trunk/docs/development/rfc/ms-rfc-12.txt
===================================================================
--- trunk/docs/development/rfc/ms-rfc-12.txt 2008-11-30 18:56:21 UTC (rev 8140)
+++ trunk/docs/development/rfc/ms-rfc-12.txt 2008-11-30 19:03:47 UTC (rev 8141)
@@ -1,4 +1,4 @@
-.. _rfc12:
+MapScript.. _rfc12:
=========================================================
MS RFC 12: C code Unit tests
@@ -12,14 +12,15 @@
--------
Unit tests are a simple but effective way of checking progress
and code correctness while programming. Mapserver already has unit tests
-for python mapscript and a functional testing suite but lacks
+for python MapScript and a functional testing suite but lacks
unit tests for the C code which represents the core of its functionality.
This rfc outlines how unit tests can be (gradually) added to the usual
-development cycle of mapserver, without pretending that developers
+development cycle of MapServer, without pretending that developers
switch to extreme programming or adopt test driven development.
-Issue #1664 on bugzilla and mapserver-dev will be used to track code samples and discussion.
+Issue #1664 on bugzilla and mapserver-dev will be used to track code
+samples and discussion.
Example
-------
@@ -29,48 +30,56 @@
C programmer. This is meant to prove that unit tests do not take away
much time from developers and that in general the benefit is worth the cost.
-The example already supports all the usual preprocessor flags (USE_FLAGS like #ifdef PROJ)
-so only the relevant tests will be compiled and run. This is necessary to avoid test
-failures due to a missing feature (as happens with Python unit tests).
+The example already supports all the usual preprocessor flags (USE_FLAGS like
+#ifdef PROJ) so only the relevant tests will be compiled and run. This is
+necessary to avoid test failures due to a missing feature (as happens with
+Python unit tests).
Unit testing software
---------------------
-This rfc recommends the use of the CUnit unit testing library for the C language, version 2.0.x.
-The configure script must be updated to reflect this new dependency and the following or a similar
-text will be displayed when cunit is not found: "cunit not found, C unit testing disabled.".
+This rfc recommends the use of the CUnit unit testing library for the C
+language, version 2.0.x. The configure script must be updated to reflect this
+new dependency and the following or a similar text will be displayed when
+cunit is not found: "cunit not found, C unit testing disabled.".
-When cunit is available unit tests could be run by default at the end of the compile phase:
-this will give users some more confidence in the software they just compiled (most of
-them are linux newbies and have no experience with programming) and could help in catching
-obvious bugs (like a typo while committing to cvs).
+When cunit is available unit tests could be run by default at the end of
+the compile phase: this will give users some more confidence in the software
+they just compiled (most of them are linux newbies and have no experience
+with programming) and could help in catching obvious bugs (like a typo
+while committing to cvs).
-Unit tests are placed in the cunit subdirectory of the mapserver source
-and distributed with all future releases.
-Unit tests files should be named with respect to the original mapserver source
-file they test plus the addition of the _tests suffix: for instance unit tests for the
-mappool.c file should be placed in a file called mappool_tests.c. The files can have
-an alphanumeric code added to the suffix to keep them conveniently short
+Unit tests are placed in the cunit subdirectory of the MapServer source and
+distributed with all future releases. Unit tests files should be named with
+respect to the original MapServer source file they test plus the addition of
+the _tests suffix: for instance unit tests for the mappool.c file should be
+placed in a file called mappool_tests.c. The files can have an alphanumeric
+code added to the suffix to keep them conveniently short
(like mappool_tests_1.c, mappool_tests_1b.c or mappool_tests_umberto.c).
Usage recommendations
-----------------------
-Developers are not required to write unit tests but when they do we suggest to follow this checklist.
+Developers are not required to write unit tests but when they do we suggest to
+follow this checklist.
Developer implementing a new feature
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* she will try to reproduce the bug with a unit test; if this is not possible or seems difficult she should consider asking on mapserver-dev. The unit test must fail at this stage (if written)
+* she will try to reproduce the bug with a unit test; if this is not possible
+ or seems difficult she should consider asking on mapserver-dev. The unit
+ test must fail at this stage (if written)
-* she fixes the bug and verifies that the test written at the previous item now passes (if written)
+* she fixes the bug and verifies that the test written at the previous
+ item now passes (if written)
* she verifies that also all other tests pass and only after she commits
Developer adding functionality
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-* she writes a test that verifies the new functionality (this can also be done afterward, as we have relaxed requirements)
+* she writes a test that verifies the new functionality (this can also be
+ done afterward, as we have relaxed requirements)
* she writes the code implementing the desired functionality
@@ -81,33 +90,36 @@
General
~~~~~~~
-She will also use the usual preprocessor flags to ensure only the relevant tests
-for the current configuration context will be compiled and run. The example
-attached to issue #1664 already implements this feature.
+She will also use the usual preprocessor flags to ensure only the relevant
+tests for the current configuration context will be compiled and run. The
+example attached to issue #1664 already implements this feature.
Testing specific functionalities
--------------------------------
-Some aspects of mapserver like database connections and gd rendering are
-inherently difficult to test. This section provides guidance on how to deal with them
-in unit tests and will be expanded as new or better solutions are devised.
+Some aspects of MapServer like database connections and gd rendering are
+inherently difficult to test. This section provides guidance on how to deal
+with them in unit tests and will be expanded as new or better solutions
+are devised.
Database connections
~~~~~~~~~~~~~~~~~~~~
-Database connections generally require a specific setup so that expected tables, data and
-possibly other structures are in place. While this should be a long term goal in the short term
-unit tests could be limited to comparing the sql query against the expected one.
+Database connections generally require a specific setup so that expected
+tables, data and possibly other structures are in place. While this should be
+a long term goal in the short term unit tests could be limited to
+comparing the sql query against the expected one.
-This quite likely requires a refactoring of current postgis code.
+This quite likely requires a refactoring of current PostGIS code.
-In the future a minimal setup script should be provided to create and populate the database for the user (if she desires to do so).
+In the future a minimal setup script should be provided to create and
+populate the database for the user (if she desires to do so).
GD (and others) rendering engines
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Taking inspiration from the perl GD module a set of images must be produced and
-then compared against those produced by mapserver. This kind of operation is
+then compared against those produced by MapServer. This kind of operation is
already performed by the msautotest suite, so effort should rather go toward
improving that instead of implementing yet another gd test suite.
@@ -117,7 +129,7 @@
Note: The author is not an expert here
In this case unit tests can be used to verify that for certain requests (possibly
-using the test data supplied with mapserver) the string returned by mapserver
+using the test data supplied with MapServer) the string returned by MapServer
equals the expected one.
A refactoring of existing code could be necessary.
@@ -125,7 +137,8 @@
Mapscript
~~~~~~~~~
-Unit tests should be developed by the mapscript mantainers by following the guidelines given here.
+Unit tests should be developed by the MapScript mantainers by following the
+guidelines given here.
Running unit tests and functional tests ( Continuos integration )
-----------------------------------------------------------------
@@ -134,7 +147,8 @@
Effort should be put toward developing a build system capable of
-a. testing the overall build/test of mapserver and of the various mapscripts with different configure options
+a. testing the overall build/test of MapServer and of the various MapServers
+ with different configure options
b. and integrating those results with the msautotest suite.
Modified: trunk/docs/msdocs_style.txt
===================================================================
--- trunk/docs/msdocs_style.txt 2008-11-30 18:56:21 UTC (rev 8140)
+++ trunk/docs/msdocs_style.txt 2008-11-30 19:03:47 UTC (rev 8141)
@@ -19,6 +19,8 @@
MapScript instead of mapscript, Mapscript, or map script.
+PostGIS instead of postgis.
+
HowTo instead of howto or HOWTO.
More information about the mapserver-commits
mailing list