From d02e9ede9aebc10d63007ca8d18650fad6d301d7 Mon Sep 17 00:00:00 2001 From: Kristian Evers Date: Thu, 10 May 2018 00:23:48 +0200 Subject: 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. --- docs/source/community/channels.rst | 37 +++++ docs/source/community/code_contributions.rst | 153 +++++++++++++++++++ docs/source/community/contributing.rst | 173 ++++++++++++++++++++++ docs/source/community/index.rst | 18 +++ docs/source/contributing.rst | 173 ---------------------- docs/source/development/for_proj_contributors.rst | 153 ------------------- docs/source/development/index.rst | 1 - docs/source/index.rst | 6 +- 8 files changed, 382 insertions(+), 332 deletions(-) create mode 100644 docs/source/community/channels.rst create mode 100644 docs/source/community/code_contributions.rst create mode 100644 docs/source/community/contributing.rst create mode 100644 docs/source/community/index.rst delete mode 100644 docs/source/contributing.rst delete mode 100644 docs/source/development/for_proj_contributors.rst (limited to 'docs/source') 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 `__. +- 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 `__ and the `GitHub +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 `__ and read the +archive `here `__. + +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 `__ 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 `__. 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 `__. The website is generated +with `Sphinx `__. Contributions to +the documentation should be made as `Pull +Requests `__ 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 ` + +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 `__ +- `GitHub pull request + documentation `__ + +Acknowledgements +---------------- + +The *code contribution* section of this CONTRIBUTING file is inspired by +`PDAL's `__ +and the *legalese* section is modified from `GDAL committer +guidelines `__ + 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 diff --git a/docs/source/contributing.rst b/docs/source/contributing.rst deleted file mode 100644 index 368f659f..00000000 --- a/docs/source/contributing.rst +++ /dev/null @@ -1,173 +0,0 @@ -.. _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 `__ and the `GitHub -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 `__ and read the -archive `here `__. - -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 `__ 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 `__. 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 `__. The website is generated -with `Sphinx `__. Contributions to -the documentation should be made as `Pull -Requests `__ on GitHub. - -If you intend to document one of PROJ's supported projections please -use the `Mercator projection `__ -as a template. - -Code contributions ------------------- - -See :doc:`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 `__ -- `GitHub pull request - documentation `__ - -Acknowledgements ----------------- - -The *code contribution* section of this CONTRIBUTING file is inspired by -`PDAL's `__ -and the *legalese* section is modified from `GDAL committer -guidelines `__ - diff --git a/docs/source/development/for_proj_contributors.rst b/docs/source/development/for_proj_contributors.rst deleted file mode 100644 index d85f5cb1..00000000 --- a/docs/source/development/for_proj_contributors.rst +++ /dev/null @@ -1,153 +0,0 @@ -.. _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 `__. -- 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 0a5fea60..3f8a7bf6 100644 --- a/docs/source/development/index.rst +++ b/docs/source/development/index.rst @@ -19,4 +19,3 @@ PROJ project or using the library in their own software. cmake bindings migration - for_proj_contributors diff --git a/docs/source/index.rst b/docs/source/index.rst index 5eb521c8..03e993ec 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -41,16 +41,12 @@ Documentation resource_files geodesic development/index + community/index faq - contributing glossary license references -Mailing List -================================================================================ - -The PROJ mailing list can be found at http://lists.maptools.org/mailman/listinfo/proj Indices and tables ================== -- cgit v1.2.3