diff options
Diffstat (limited to 'docs/source/development/for_proj_contributors.rst')
| -rw-r--r-- | docs/source/development/for_proj_contributors.rst | 80 |
1 files changed, 75 insertions, 5 deletions
diff --git a/docs/source/development/for_proj_contributors.rst b/docs/source/development/for_proj_contributors.rst index 81b692a6..d85f5cb1 100644 --- a/docs/source/development/for_proj_contributors.rst +++ b/docs/source/development/for_proj_contributors.rst @@ -6,16 +6,86 @@ Development rules and tools for PROJ code contributors This is a guide for PROJ, casual or regular, code contributors. -Coding rules +Code contributions. ############################################################################### -To be formalized. Current rule is do like existing surrounding code... +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, @@ -37,7 +107,7 @@ 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. @@ -78,6 +148,6 @@ 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`` |