CONTRIBUTING.md

   1 # Nominatim contribution guidelines
   2
   3 ## Reporting Bugs
   4
   5 Bugs can be reported at https://github.com/openstreetmap/Nominatim/issues.
   6 Please always open a separate issue for each problem. In particular, do
   7 not add your bugs to closed issues. They may looks similar to you but
   8 often are completely different from the maintainer's point of view.
   9
  10 ### When Reporting Bad Search Results...
  11
  12 Please make sure to add the following information:
  13
  14  * the URL of the query that produces the bad result
  15  * the result you are getting
  16  * the expected result, preferably a link to the OSM object you want to find,
  17    otherwise an address that is as precise as possible
  18
  19  To get the link to the OSM object, you can try the following:
  20
  21  * go to https://openstreetmap.org
  22  * zoom to the area of the map where you expect the result and
  23    zoom in as much as possible
  24  * click on the question mark on the right side of the map,
  25    then with the queston cursor on the map where your object is located
  26  * find the object of interest in the list that appears on the left side
  27  * click on the object and report the URL back that the browser shows
  28
  29 ### When Reporting Problems with your Installation...
  30
  31 Please add the following information to your issue:
  32
  33  * hardware configuration: RAM size, kind of disks
  34  * Operating system (also mention if you are running on a cloud server)
  35  * Postgres and Postgis version
  36  * list of settings you changed in your Postgres configuration
  37  * Nominatim version (commit id, if you run from the github repo)
  38  * (if applicable) exact command line of the command that was causing the issues
  39
  40
  41 ## Workflow for Pull Requests
  42
  43 We love to get pull reuqests from you. We operate the "Fork & Pull" model
  44 explained at
  45
  46 https://help.github.com/articles/using-pull-requests
  47
  48 You should fork the project into your own repo, create a topic branch
  49 there and then make one or more pull requests back to the openstreetmap repository.
  50 Your pull requests will then be reviewed and discussed. Please be aware
  51 that you are responsible for your pull requests. You should be prepared
  52 to get change requests because as the maintainers we have to make sure
  53 that your contribution fits well with the rest of the code. Please make
  54 sure that you have time to react to these comments and amend the code or
  55 engage in a conversion. Do not expect that others will pick up your code,
  56 it will almost never happen.
  57
  58 Please open a separate pull request for each issue you want to address.
  59 Don't mix multiple changes. In particular, don't mix style cleanups with
  60 feature pull requests. If you plan to make larger changes, please open
  61 an issue first or comment on the appropriate issue already existing so
  62 that duplicate work can be avoided.
  63
  64 ## Coding style
  65
  66 Nominatim historically hasn't followed a particular coding style but we
  67 are in process of consolodating the style. The following rules apply:
  68
  69  * Python code uses the official Python style
  70  * indention
  71    * SQL use 2 spaces
  72    * all other file types use 4 spaces
  73    * [BSD style](https://en.wikipedia.org/wiki/Indent_style#Allman_style) for braces
  74  * spaces
  75    * spaces before and after equal signs and operators
  76    * no trailing spaces
  77    * no spaces after opening and before closing bracket
  78    * leave out space between a function name and bracket
  79      but add one between control statement(if, while, etc.) and bracket
  80
  81 The coding style is enforced with PHPCS and can be tested with:
  82
  83 ```
  84   phpcs --report-width=120 --colors */**.php
  85 ```
  86
  87 ## Testing
  88
  89 Before submitting a pull request make sure that the following tests pass:
  90
  91 ```
  92   cd test/bdd
  93   behave -DBUILDDIR=<builddir> db osm2pgsql
  94 ```
  95
  96 ```
  97   cd test/php
  98   phpunit ./
  99 ```