CONTRIBUTE.md

   1 # Developing Nominatim-UI
   2
   3 [![Continuous Integration](https://github.com/osm-search/nominatim-ui/actions/workflows/ci.yml/badge.svg)](https://github.com/osm-search/nominatim-ui/actions/workflows/ci.yml)
   4
   5 ## Background
   6
   7 Uses [Svelte](https://svelte.dev/) framework,
   8 [Leaflet](https://leafletjs.com/) for map interaction,
   9 [Bootstrap](https://getbootstrap.com/) for layout styling.
  10
  11 The user interface used to be included in the geocoder. Thus the
  12 first version avoided being a redesign and still uses some of the
  13 same configuration values. Version 2 was a full refactor using
  14 Svelte. Version 3 added theme and easier configuration.
  15
  16
  17
  18 ## Building the frontend
  19
  20 * Install dependencies
  21
  22    ```
  23    yarn install
  24    ```
  25
  26 * After you change files in `src` directory run
  27
  28    ```
  29    yarn dev
  30    ```
  31    which will start a webserver on port 9880 and auto-reloads
  32    whenever you edit files. Configuration in `rollup.config.js`.
  33
  34 ## Testing
  35
  36 The `test/` setup uses [Mocha](https://mochajs.org/) to run tests. Tests use [Puppeteer](https://pptr.dev/) to control a Google Chrome headless browser and evaluate with [Assert](https://nodejs.org/api/assert.html).
  37
  38
  39 * Run integration test suite (configuration in `.mocharc.js`)
  40
  41    ```
  42    yarn test
  43    API_ON_SAME_PORT=1 yarn test
  44    ```
  45
  46    Setting API_ON_SAME_PORT simulates having both the API and UI on the same server
  47    port. That's a rare setup but something https://nominatim.openstreetmap.org/ does
  48    so worth testing.
  49
  50    To run a single test file only
  51
  52    ```
  53    yarn run rollup -c && yarn run mocha test/details.js
  54    ```
  55
  56 * Run syntax linter (configuration in `.eslint.js`)
  57
  58    ```
  59    yarn lint
  60    ```
  61
  62
  63 ## Prepare a release
  64
  65 1. Update version number in `package.json` file
  66
  67 2. Update `CHANGES.md` file
  68
  69 3. Commit your changes: `git add... `, `git commit ...`, `git push ...` etc
  70
  71 4. Tag release: `git tag THE_VERSION_NUMBER`, `git push --tags`
  72
  73 5. Create release on https://github.com/osm-search/nominatim-ui/releases
  74    This (a triggered Github Action) will run `yarn build` and add the `dist/build/bundle.*` files.