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 look 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 conversation. 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 ### Using AI-assisted code generators
  34
  35 PRs that include AI-generated content, may that be in code, in the PR
  36 description or in documentation need to
  37
  38 1. clearly mark the AI-generated sections as such, for example, by
  39    mentioning all use of AI in the PR description, and
  40 2. include proof that you have run the generated code on an actual
  41    installation of Nominatim. Adding and executing tests will not be
  42    sufficient. You need to show that the code actually solves the problem
  43    the PR claims to solve.
  44
  45 ## Getting Started with Development
  46
  47 Please see the development section of the Nominatim documentation for
  48
  49 * [an architecture overview](https://nominatim.org/release-docs/develop/develop/overview/)
  50   and backgrounds on some of the algorithms
  51 * [how to set up a development environment](https://nominatim.org/release-docs/develop/develop/Development-Environment/)
  52 * and background on [how tests are organised](https://nominatim.org/release-docs/develop/develop/Testing/)
  53
  54
  55 ## Coding style
  56
  57 Nominatim historically hasn't followed a particular coding style but we
  58 are in process of consolidating the style. The following rules apply:
  59
  60  * Python code uses the official Python style
  61  * indentation
  62    * SQL use 2 spaces
  63    * all other file types use 4 spaces
  64    * [BSD style](https://en.wikipedia.org/wiki/Indent_style#Allman_style) for braces
  65  * spaces
  66    * spaces before and after equal signs and operators
  67    * no trailing spaces
  68    * no spaces after opening and before closing bracket
  69    * leave out space between a function name and bracket
  70      but add one between control statement(if, while, etc.) and bracket
  71
  72 The coding style is enforced with flake8. It can be tested with:
  73
  74 ```
  75 make lint
  76 ```
  77
  78 ## Testing
  79
  80 Before submitting a pull request make sure that the tests pass:
  81
  82 ```
  83   make tests
  84 ```
  85
  86 ## Releases
  87
  88 Nominatim follows semantic versioning. Major releases are done for large changes
  89 that require (or at least strongly recommend) a reimport of the databases.
  90 Minor releases can usually be applied to existing databases. Patch releases
  91 contain bug fixes only and are released from a separate branch where the
  92 relevant changes are cherry-picked from the master branch.
  93
  94 Checklist for releases:
  95
  96 * [ ] increase versions in
  97   * `src/nominatim_api/version.py`
  98   * `src/nominatim_db/version.py`
  99 * [ ] update `ChangeLog` (copy information from patch releases from release branch)
 100 * [ ] complete `docs/admin/Migration.md`
 101 * [ ] update EOL dates in `SECURITY.md`
 102 * [ ] commit and make sure CI tests pass
 103 * [ ] update OSMF production repo and release new version -post1 there
 104 * [ ] test migration
 105   * download, build and import previous version
 106   * migrate using master version
 107   * run updates using master version
 108 * [ ] prepare tarball:
 109   * `git clone https://github.com/osm-search/Nominatim` (switch to right branch!)
 110   * `rm -r .git*`
 111   * copy country data into `data/`
 112   * add version to base directory and package
 113 * [ ] upload tarball to https://nominatim.org
 114 * [ ] prepare documentation
 115   * check out new docs branch
 116   * change git checkout instructions to tarball download instructions or adapt version on existing ones
 117   * build documentation and copy to https://github.com/osm-search/nominatim-org-site
 118   * add new version to history
 119 * [ ] check release tarball
 120   * download tarball as per new documentation instructions
 121   * compile and import Nominatim
 122   * run `nominatim --version` to confirm correct version
 123 * [ ] tag new release and add a release on github.com
 124 * [ ] build pip packages and upload to pypi
 125   * `make build`
 126   * `twine upload dist/*`