]> git.openstreetmap.org Git - nominatim.git/blob - CONTRIBUTING.md
make DB helper functions free functions
[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 ## Workflow for Pull Requests
11
12 We love to get pull requests from you. We operate the "Fork & Pull" model
13 explained at
14
15 https://help.github.com/articles/using-pull-requests
16
17 You should fork the project into your own repo, create a topic branch
18 there and then make one or more pull requests back to the openstreetmap repository.
19 Your pull requests will then be reviewed and discussed. Please be aware
20 that you are responsible for your pull requests. You should be prepared
21 to get change requests because as the maintainers we have to make sure
22 that your contribution fits well with the rest of the code. Please make
23 sure that you have time to react to these comments and amend the code or
24 engage in a conversion. Do not expect that others will pick up your code,
25 it will almost never happen.
26
27 Please open a separate pull request for each issue you want to address.
28 Don't mix multiple changes. In particular, don't mix style cleanups with
29 feature pull requests. If you plan to make larger changes, please open
30 an issue first or comment on the appropriate issue already existing so
31 that duplicate work can be avoided.
32
33 ## Coding style
34
35 Nominatim historically hasn't followed a particular coding style but we
36 are in process of consolidating the style. The following rules apply:
37
38  * Python code uses the official Python style
39  * indentation
40    * SQL use 2 spaces
41    * all other file types use 4 spaces
42    * [BSD style](https://en.wikipedia.org/wiki/Indent_style#Allman_style) for braces
43  * spaces
44    * spaces before and after equal signs and operators
45    * no trailing spaces
46    * no spaces after opening and before closing bracket
47    * leave out space between a function name and bracket
48      but add one between control statement(if, while, etc.) and bracket
49  * for PHP variables use CamelCase with a prefixing letter indicating the type
50    (i - integer, f - float, a - array, s - string, o - object)
51
52 The coding style is enforced with PHPCS and pylint. It can be tested with:
53
54 ```
55 phpcs --report-width=120 --colors .
56 pylint3 --extension-pkg-whitelist=osmium nominatim
57 ```
58
59 ## Testing
60
61 Before submitting a pull request make sure that the tests pass:
62
63 ```
64   cd build
65   make test
66 ```
67
68 ## Releases
69
70 Nominatim follows semantic versioning. Major releases are done for large changes
71 that require (or at least strongly recommend) a reimport of the databases.
72 Minor releases can usually be applied to existing databases. Patch releases
73 contain bug fixes only and are released from a separate branch where the
74 relevant changes are cherry-picked from the master branch.
75
76 Checklist for releases:
77
78 * [ ] increase version in `nominatim/version.py` and CMakeLists.txt
79 * [ ] update `ChangeLog` (copy information from patch releases from release branch)
80 * [ ] complete `docs/admin/Migration.md`
81 * [ ] update EOL dates in `SECURITY.md`
82 * [ ] commit and make sure CI tests pass
83 * [ ] test migration
84   * download, build and import previous version
85   * migrate using master version
86   * run updates using master version
87 * [ ] prepare tarball:
88   * `git clone --recursive https://github.com/osm-search/Nominatim` (switch to right branch!)
89   * `rm -r .git* osm2pgsql/.git*`
90   * copy country data into `data/`
91   * add version to base directory and package
92 * [ ] upload tarball to https://nominatim.org
93 * [ ] prepare documentation
94   * check out new docs branch
95   * change git checkout instructions to tarball download instructions or adapt version on existing ones
96   * build documentation and copy to https://github.com/osm-search/nominatim-org-site
97   * add new version to history
98 * [ ] check release tarball
99   * download tarball as per new documentation instructions
100   * compile and import Nominatim
101   * run `nominatim --version` to confirm correct version
102 * [ ] tag new release and add a release on github.com