Merge pull request #864 from rouault/docs_for_developers

Add a for_proj_contributors.rst to document cppcheck, CSA and fix_typos.sh (fixes #862)

3 files changed, 155 insertions, 70 deletions

diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst
index e7a1d711..ea72bcbd 100644
--- a/docs/source/contributing.rst
+++ b/docs/source/contributing.rst
@@ -98,76 +98,7 @@ as a template.
 Code contributions
 ------------------
 
-Code contributions can be either bug fixes or new features. The process
-is the same for both, so they will be discussed together in this
-section.
-
-Making Changes
-~~~~~~~~~~~~~~
-
--  Create a topic branch from where you want to base your work.
--  You usually should base your topic branch off of the master branch.
--  To quickly create a topic branch: ``git checkout -b my-topic-branch``
--  Make commits of logical units.
--  Check for unnecessary whitespace with ``git diff --check`` before
-   committing.
--  Make sure your commit messages are in the `proper
-   format <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`__.
--  Make sure you have added the necessary tests for your changes.
--  Make sure that all tests pass
-
-Submitting Changes
-~~~~~~~~~~~~~~~~~~
-
--  Push your changes to a topic branch in your fork of the repository.
--  Submit a pull request to the PROJ repository in the OSGeo
-   organization.
--  If your pull request fixes/references an issue, include that issue
-   number in the pull request. For example:
-
-::
-
-    Wiz the bang
-
-    Fixes #123.
-
--  PROJ developers will look at your patch and take an appropriate
-   action.
-
-Coding conventions
-~~~~~~~~~~~~~~~~~~
-
-Programming language
-^^^^^^^^^^^^^^^^^^^^
-
-PROJ is developed strictly in ANSI C 89.
-
-Coding style
-^^^^^^^^^^^^
-
-We don't enforce any particular coding style, but please try to keep it
-as simple as possible. If improving existing code, please try to conform
-with the style of the locally surrounding code.
-
-Whitespace
-^^^^^^^^^^
-
-Throughout the PROJ code base you will see differing whitespace use.
-The general rule is to keep whitespace in whatever form it is in the
-file you are currently editing. If the file has a mix of tabs and space
-please convert the tabs to space in a separate commit before making any
-other changes. This makes it a lot easier to see the changes in diffs
-when evaluating the changed code. New files should use spaces as
-whitespace.
-
-File names
-^^^^^^^^^^
-
-Files in which projections are implemented are prefixed with an
-upper-case ``PJ_`` and most other files are prefixed with lower-case
-``pj_``. Some file deviate from this pattern, most of them dates back to
-the very early releases of PROJ. New contributions should follow the
-pj-prefix pattern. Unless there are obvious reasons not to.
+See :doc:`Code contributions <development/for_proj_contributors>`
 
 Legalese
 ~~~~~~~~
diff --git a/docs/source/development/for_proj_contributors.rst b/docs/source/development/for_proj_contributors.rst
new file mode 100644
index 00000000..d85f5cb1
--- /dev/null
+++ b/docs/source/development/for_proj_contributors.rst
@@ -0,0 +1,153 @@
+.. _for_proj_contributors:
+
+================================================================================
+Development rules and tools for PROJ code contributors
+================================================================================
+
+This is a guide for PROJ, casual or regular, code contributors.
+
+Code contributions.
+###############################################################################
+
+Code contributions can be either bug fixes or new features. The process
+is the same for both, so they will be discussed together in this
+section.
+
+Making Changes
+~~~~~~~~~~~~~~
+
+-  Create a topic branch from where you want to base your work.
+-  You usually should base your topic branch off of the master branch.
+-  To quickly create a topic branch: ``git checkout -b my-topic-branch``
+-  Make commits of logical units.
+-  Check for unnecessary whitespace with ``git diff --check`` before
+   committing.
+-  Make sure your commit messages are in the `proper
+   format <http://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html>`__.
+-  Make sure you have added the necessary tests for your changes.
+-  Make sure that all tests pass
+
+Submitting Changes
+~~~~~~~~~~~~~~~~~~
+
+-  Push your changes to a topic branch in your fork of the repository.
+-  Submit a pull request to the PROJ repository in the OSGeo
+   organization.
+-  If your pull request fixes/references an issue, include that issue
+   number in the pull request. For example:
+
+::
+
+    Wiz the bang
+
+    Fixes #123.
+
+-  PROJ developers will look at your patch and take an appropriate
+   action.
+
+Coding conventions
+~~~~~~~~~~~~~~~~~~
+
+Programming language
+^^^^^^^^^^^^^^^^^^^^
+
+PROJ is developed strictly in ANSI C 89.
+
+Coding style
+^^^^^^^^^^^^
+
+We don't enforce any particular coding style, but please try to keep it
+as simple as possible. If improving existing code, please try to conform
+with the style of the locally surrounding code.
+
+Whitespace
+^^^^^^^^^^
+
+Throughout the PROJ code base you will see differing whitespace use.
+The general rule is to keep whitespace in whatever form it is in the
+file you are currently editing. If the file has a mix of tabs and space
+please convert the tabs to space in a separate commit before making any
+other changes. This makes it a lot easier to see the changes in diffs
+when evaluating the changed code. New files should use spaces as
+whitespace.
+
+File names
+^^^^^^^^^^
+
+Files in which projections are implemented are prefixed with an
+upper-case ``PJ_`` and most other files are prefixed with lower-case
+``pj_``. Some file deviate from this pattern, most of them dates back to
+the very early releases of PROJ. New contributions should follow the
+pj-prefix pattern. Unless there are obvious reasons not to.
+
+
+Tools
+###############################################################################
+
+cppcheck static analyzer
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+You can run locally ``scripts/cppcheck.sh`` that is a wrapper script around the
+cppcheck utility. It is known to work with cppcheck 1.61 of Ubuntu Trusty 14.0,
+since this is what is currently used on Travis-CI
+(``travis/linux_gcc/before_install.sh``).
+At the time of writing, this also works with cppcheck 1.72 of Ubuntu Xenial
+16.04, and latest cppcheck
+master.
+
+cppcheck can have false positives. In general, it is preferable to rework the
+code a bit to make it more 'obvious' and avoid those false positives. When not
+possible, you can add a comment in the code like 
+
+::
+
+    /* cppcheck-suppress duplicateBreak */
+
+in the preceding line. Replace
+duplicateBreak with the actual name of the violated rule emitted by cppcheck.
+
+CLang Static Analyzer (CSA)
+~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+CSA is run by the ``travis/csa`` build configuration. You may also run it locally.
+
+Preliminary step: install clang. For example:
+
+::
+
+    wget http://releases.llvm.org/6.0.0/clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.tar.xz
+    tar xJf clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04.tar.xz
+
+Run configure under the scan-build utility of clang:
+
+::
+
+    ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build ./configure
+
+Build under scan-build:
+
+::
+
+    ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-build make [-j8]
+
+If CSA finds errors, they will be emitted during the build. And in which case,
+at the end of the build process, scan-build will emit a warning message
+indicating errors have been found and how to display the error report. This
+is with someling like
+
+::
+
+    ./clang+llvm-6.0.0-x86_64-linux-gnu-ubuntu-14.04/bin/scan-view /tmp/scan-build-2018-03-15-121416-17476-1
+
+
+This will open a web browser with the interactive report.
+
+CSA may also have false positives. In general, this happens when the code is
+non-trivial / makes assumptions that hard to check at first sight. You will
+need to add extra checks or rework it a bit to make it more "obvious" for CSA.
+This will also help humans reading your code !
+
+Typo detection and fixes
+~~~~~~~~~~~~~~~~~~~~~~~~
+
+Run ``scripts/fix_typos.sh``
diff --git a/docs/source/development/index.rst b/docs/source/development/index.rst
index 3f8a7bf6..0a5fea60 100644
--- a/docs/source/development/index.rst
+++ b/docs/source/development/index.rst
@@ -19,3 +19,4 @@ PROJ project or using the library in their own software.
    cmake
    bindings
    migration
+   for_proj_contributors