]> git.openstreetmap.org Git - nominatim.git/blob - CONTRIBUTING.md
Merge branch 'housenumber-zero' of https://github.com/mtmail/Nominatim into mtmail...
[nominatim.git] / 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 Bugs...
30
31 Please add the following information to your issue:
32
33  * hardware configuration: RAM size, CPUs, kind and size of disks
34  * Operating system (also mention if you are running on a cloud service)
35  * Postgres and Postgis version
36  * list of settings you changed in your Postgres configuration
37  * Nominatim version (release version or,
38    if you run from the git repo, the output of `git rev-parse HEAD`)
39  * (if applicable) exact command line of the command that was causing the issue
40
41 Bug reports that do not include extensive information about your system,
42 about the problem and about what you have been trying to debug the problem
43 will be closed.
44
45 ## Workflow for Pull Requests
46
47 We love to get pull requests from you. We operate the "Fork & Pull" model
48 explained at
49
50 https://help.github.com/articles/using-pull-requests
51
52 You should fork the project into your own repo, create a topic branch
53 there and then make one or more pull requests back to the openstreetmap repository.
54 Your pull requests will then be reviewed and discussed. Please be aware
55 that you are responsible for your pull requests. You should be prepared
56 to get change requests because as the maintainers we have to make sure
57 that your contribution fits well with the rest of the code. Please make
58 sure that you have time to react to these comments and amend the code or
59 engage in a conversion. Do not expect that others will pick up your code,
60 it will almost never happen.
61
62 Please open a separate pull request for each issue you want to address.
63 Don't mix multiple changes. In particular, don't mix style cleanups with
64 feature pull requests. If you plan to make larger changes, please open
65 an issue first or comment on the appropriate issue already existing so
66 that duplicate work can be avoided.
67
68 ## Coding style
69
70 Nominatim historically hasn't followed a particular coding style but we
71 are in process of consolidating the style. The following rules apply:
72
73  * Python code uses the official Python style
74  * indention
75    * SQL use 2 spaces
76    * all other file types use 4 spaces
77    * [BSD style](https://en.wikipedia.org/wiki/Indent_style#Allman_style) for braces
78  * spaces
79    * spaces before and after equal signs and operators
80    * no trailing spaces
81    * no spaces after opening and before closing bracket
82    * leave out space between a function name and bracket
83      but add one between control statement(if, while, etc.) and bracket
84  * for PHP variables use CamelCase with a prefixing letter indicating the type
85    (i - integer, f - float, a - array, s - string, o - object)
86
87 The coding style is enforced with PHPCS and can be tested with:
88
89 ```
90   phpcs --report-width=120 --colors .
91 ```
92
93 ## Testing
94
95 Before submitting a pull request make sure that the following tests pass:
96
97 ```
98   cd test/bdd
99   behave -DBUILDDIR=<builddir> db osm2pgsql
100 ```
101
102 ```
103   cd test/php
104   phpunit ./
105 ```