Create "Community" section at top level of docs

Mailing list section from frontpage moved to the new section. So is the
contributing and for_proj_contributors pages.

4 files changed, 381 insertions, 0 deletions

diff --git a/docs/source/community/channels.rst b/docs/source/community/channels.rst
new file mode 100644
index 00000000..ea12c3f7
--- /dev/null
+++ b/docs/source/community/channels.rst
@@ -0,0 +1,37 @@
+.. _channels:
+
+===========================
+Communication channels
+===========================
+
+Mailing list
+-------------------------------------------------------------------------------
+
+Users and developers of the library are using the mailing list to discuss all
+things related to PROJ. The mailing list is the primary forum for asking for
+help with use of PROJ. The mailing list is also used for announcements, discussions
+about the development of the library and from time to time interesting discussions
+on geodesy appear as well. You are more than welcome to join in on the discussions!
+
+
+The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj
+
+
+GitHub
+-------------------------------------------------------------------------------
+
+GitHub is the development platform we use for collaborating on the PROJ code.
+We use GitHub to keep track of the changes in the code and to index bug reports
+and feature requests. We are happy to take contributions in any form, either
+as code, bug reports, documentation or feature requests. See :ref:`contributing`
+for more info on how you can help improve PROJ.
+
+The PROJ GitHub page can be found at https://github.com/OSGeo/proj.4
+
+.. note::
+
+    The issue tracker on GitHub is only meant to keep track of bugs, feature
+    request and other things related to the development of PROJ. Please ask
+    your questions about the use of PROJ on the mailing list instead.
+
+
diff --git a/docs/source/community/code_contributions.rst b/docs/source/community/code_contributions.rst
new file mode 100644
index 00000000..ef144399
--- /dev/null
+++ b/docs/source/community/code_contributions.rst
@@ -0,0 +1,153 @@
+.. _code_contributions:
+
+================================================================================
+Guidelines 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/community/contributing.rst b/docs/source/community/contributing.rst
new file mode 100644
index 00000000..d56aef6e
--- /dev/null
+++ b/docs/source/community/contributing.rst
@@ -0,0 +1,173 @@
+.. _contributing:
+
+===========================
+Contributing
+===========================
+
+PROJ has a wide and varied user base. Some are highly skilled
+geodesists with a deep knowledge of map projections and reference
+systems, some are GIS software developers and others are GIS users. All
+users, regardless of the profession or skill level, has the ability to
+contribute to PROJ. Here's a few suggestion on how:
+
+-  Help PROJ-users that is less experienced than yourself.
+-  Write a bug report
+-  Request a new feature
+-  Write documentation for your favorite map projection
+-  Fix a bug
+-  Implement a new feature
+
+In the following sections you can find some guidelines on how to
+contribute. As PROJ is managed on GitHub most contributions require
+that you have a GitHub account. Familiarity with
+`issues <https://guides.github.com/features/issues/>`__ and the `GitHub
+Flow <https://guides.github.com/introduction/flow/>`__ is an advantage.
+
+Help a fellow PROJ user
+-------------------------
+
+The main forum for support for PROJ is the mailing list. You can
+subscribe to the mailing list
+`here <http://lists.maptools.org/mailman/listinfo/proj>`__ and read the
+archive `here <http://lists.maptools.org/pipermail/proj/>`__.
+
+If you have questions about the usage of PROJ the mailing list is also
+the place to go. Please *do not* use the GitHub issue tracker as a
+support forum. Your question is much more likely to be answered on the
+mailing list, as many more people follow that than the issue tracker.
+
+Adding bug reports
+------------------
+
+Bug reports are handled in the `issue
+tracker <https://github.com/OSGeo/proj.4/issues>`__ on PROJ's home on
+GitHub. Writing a good bug report is not easy. But fixing a poorly
+documented bug is not easy either, so please put in the effort it takes
+to create a thorough bug report.
+
+A good bug report includes at least:
+
+-  A title that quickly explains the problem
+-  A description of the problem and how it can be reproduced
+-  Version of PROJ being used
+-  Version numbers of any other relevant software being used, e.g.
+   operating system
+-  A description of what already has been done to solve the problem
+
+The more information that is given up front, the more likely it is that
+a developer will find interest in solving the problem. You will probably
+get follow-up questions after submitting a bug report. Please answer
+them in a timely manner if you have an interest in getting the issue
+solved.
+
+Finally, please only submit bug reports that are actually related to
+PROJ. If the issue materializes in software that uses PROJ it is
+likely a problem with that particular software. Make sure that it
+actually is a PROJ problem before you submit an issue. If you can
+reproduce the problem only by using tools from PROJ it is definitely a
+problem with PROJ.
+
+Feature requests
+----------------
+
+Got an idea for a new feature in PROJ? Submit a thorough description
+of the new feature in the `issue
+tracker <https://github.com/OSGeo/proj.4/issues>`__. Please include any
+technical documents that can help the developer make the new feature a
+reality. An example of this could be a publicly available academic paper
+that describes a new projection. Also, including a numerical test case
+will make it much easier to verify that an implementation of your
+requested feature actually works as you expect.
+
+Note that not all feature requests are accepted.
+
+Write documentation
+-------------------
+
+PROJ is in dire need of better documentation. Any contributions of
+documentation are greatly appreciated. The PROJ documentation is
+available on `proj4.org <http://proj4.org>`__. The website is generated
+with `Sphinx <http://www.sphinx-doc.org/en/stable/>`__. Contributions to
+the documentation should be made as `Pull
+Requests <https://github.com/OSGeo/proj.4/pulls>`__ on GitHub.
+
+If you intend to document one of PROJ's supported projections please
+use the :doc:`Mercator projection <../operations/projections/merc>`
+as a template.
+
+Code contributions
+------------------
+
+See :doc:`Code contributions <code_contributions>`
+
+Legalese
+~~~~~~~~
+
+Committers are the front line gatekeepers to keep the code base clear of
+improperly contributed code. It is important to the PROJ users,
+developers and the OSGeo foundation to avoid contributing any code to
+the project without it being clearly licensed under the project license.
+
+Generally speaking the key issues are that those providing code to be
+included in the repository understand that the code will be released
+under the MIT/X license, and that the person providing the code has the
+right to contribute the code. For the committer themselves understanding
+about the license is hopefully clear. For other contributors, the
+committer should verify the understanding unless the committer is very
+comfortable that the contributor understands the license (for instance
+frequent contributors).
+
+If the contribution was developed on behalf of an employer (on work
+time, as part of a work project, etc) then it is important that an
+appropriate representative of the employer understand that the code will
+be contributed under the MIT/X license. The arrangement should be
+cleared with an authorized supervisor/manager, etc.
+
+The code should be developed by the contributor, or the code should be
+from a source which can be rightfully contributed such as from the
+public domain, or from an open source project under a compatible
+license.
+
+All unusual situations need to be discussed and/or documented.
+
+Committers should adhere to the following guidelines, and may be
+personally legally liable for improperly contributing code to the source
+repository:
+
+-  Make sure the contributor (and possibly employer) is aware of the
+   contribution terms.
+-  Code coming from a source other than the contributor (such as adapted
+   from another project) should be clearly marked as to the original
+   source, copyright holders, license terms and so forth. This
+   information can be in the file headers, but should also be added to
+   the project licensing file if not exactly matching normal project
+   licensing (COPYING).
+-  Existing copyright headers and license text should never be stripped
+   from a file. If a copyright holder wishes to give up copyright they
+   must do so in writing to the foundation before copyright messages are
+   removed. If license terms are changed it has to be by agreement
+   (written in email is ok) of the copyright holders.
+-  Code with licenses requiring credit, or disclosure to users should be
+   added to COPYING.
+-  When substantial contributions are added to a file (such as
+   substantial patches) the author/contributor should be added to the
+   list of copyright holders for the file.
+-  If there is uncertainty about whether a change is proper to
+   contribute to the code base, please seek more information from the
+   project steering committee, or the foundation legal counsel.
+
+Additional Resources
+--------------------
+
+-  `General GitHub documentation <http://help.github.com/>`__
+-  `GitHub pull request
+   documentation <https://help.github.com/articles/about-pull-requests/>`__
+
+Acknowledgements
+----------------
+
+The *code contribution* section of this CONTRIBUTING file is inspired by
+`PDAL's <https://github.com/PDAL/PDAL/blob/master/CONTRIBUTING.md>`__
+and the *legalese* section is modified from `GDAL committer
+guidelines <https://trac.osgeo.org/gdal/wiki/rfc3_commiters>`__
+
diff --git a/docs/source/community/index.rst b/docs/source/community/index.rst
new file mode 100644
index 00000000..07308753
--- /dev/null
+++ b/docs/source/community/index.rst
@@ -0,0 +1,18 @@
+.. _community:
+
+Community
+===============================================================================
+
+The PROJ community is what makes the software stand out from its competitors.
+PROJ is used and developed by group of very enthusiastic, knowledgeable and
+friendly people. Whether you are a first time user of PROJ or a long-time
+contributor the community is always very welcoming.
+
+.. only:: html
+
+    .. toctree::
+       :maxdepth: 1
+
+       channels
+       contributing
+       code_contributions