Merge pull request #2869 from mtmail/improve-tiger-install-doc

[nominatim.git] / CONTRIBUTING.md

diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md
index 9d52ee663d1695ece083ed905806f21911e1ce26..e031cd91116df9030c0e82f4f1dd1eebcbcfe37b 100644 (file)
--- a/CONTRIBUTING.md
+++ b/CONTRIBUTING.md
@@ -1,24 +1,44 @@
 # Nominatim contribution guidelines
 
-## Workflow
+## Reporting Bugs
 
-We operate the "Fork & Pull" model explained at
+Bugs can be reported at https://github.com/openstreetmap/Nominatim/issues.
+Please always open a separate issue for each problem. In particular, do
+not add your bugs to closed issues. They may looks similar to you but
+often are completely different from the maintainer's point of view.
+
+## Workflow for Pull Requests
+
+We love to get pull requests from you. We operate the "Fork & Pull" model
+explained at
 
 https://help.github.com/articles/using-pull-requests
 
 You should fork the project into your own repo, create a topic branch
 there and then make one or more pull requests back to the openstreetmap repository.
-Your pull requests will then be reviewed and discussed.
+Your pull requests will then be reviewed and discussed. Please be aware
+that you are responsible for your pull requests. You should be prepared
+to get change requests because as the maintainers we have to make sure
+that your contribution fits well with the rest of the code. Please make
+sure that you have time to react to these comments and amend the code or
+engage in a conversion. Do not expect that others will pick up your code,
+it will almost never happen.
+
+Please open a separate pull request for each issue you want to address.
+Don't mix multiple changes. In particular, don't mix style cleanups with
+feature pull requests. If you plan to make larger changes, please open
+an issue first or comment on the appropriate issue already existing so
+that duplicate work can be avoided.
 
 ## Coding style
 
 Nominatim historically hasn't followed a particular coding style but we
-are in process of consolodating the style. The following rules apply:
+are in process of consolidating the style. The following rules apply:
 
  * Python code uses the official Python style
- * indention
+ * indentation
    * SQL use 2 spaces
-   * all other use files TABs
+   * all other file types use 4 spaces
    * [BSD style](https://en.wikipedia.org/wiki/Indent_style#Allman_style) for braces
  * spaces
    * spaces before and after equal signs and operators
@@ -26,22 +46,21 @@ are in process of consolodating the style. The following rules apply:
    * no spaces after opening and before closing bracket
    * leave out space between a function name and bracket
      but add one between control statement(if, while, etc.) and bracket
+ * for PHP variables use CamelCase with a prefixing letter indicating the type
+   (i - integer, f - float, a - array, s - string, o - object)
 
+The coding style is enforced with PHPCS and pylint. It can be tested with:
 
-This coding style must be applied to any new or changed code. You are also
-welcome to fix the coding style of existing code but please submit separate
-PRs for this.
+```
+phpcs --report-width=120 --colors .
+pylint3 --extension-pkg-whitelist=osmium nominatim
+```
 
 ## Testing
 
-Before submitting a pull request make sure that the following tests pass:
-
-```
-  cd tests
-  NOMINATIM_DIR=<builddir> lettuce -t -Fail -t -Tiger features/db features/osm2pgsql
-```
+Before submitting a pull request make sure that the tests pass:
 
 ```
-  cd test-php
-  phpunit ./
+  cd build
+  make test
 ```