rollup 4.x needs nodejs 18

[nominatim-ui.git] / CONTRIBUTE.md

diff --git a/CONTRIBUTE.md b/CONTRIBUTE.md
index de818e86ad548e4e91d00e7ce7c1e643edba3311..72248321ef3327e906147149d01491fd3c016a5c 100644 (file)
--- a/CONTRIBUTE.md
+++ b/CONTRIBUTE.md
@@ -1,17 +1,18 @@
 # Developing Nominatim-UI
 
+[![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)
+
 ## Background
 
+Uses [Svelte](https://svelte.dev/) framework,
+[Leaflet](https://leafletjs.com/) for map interaction,
+[Bootstrap](https://getbootstrap.com/) for layout styling.
+
 The user interface used to be included in the geocoder. Thus the
-first version avoid being a redesign and still uses some of the
-same configuration values. For simplicity it's not a single
-page application (SPA) written in a framework though it could
-be in the future if complexity grows.
+first version avoided being a redesign and still uses some of the
+same configuration values. Version 2 was a full refactor using
+Svelte. Version 3 added theme and easier configuration.
 
-Uses [jQuery](https://jquery.com/) for browser DOM interaction,
-[handlebar](http://handlebarsjs.com/) templates to build pages,
-[leaflet](https://leafletjs.com/) for map interaction,
-[bootstrap](https://getbootstrap.com/) for layout styling.
 
 
 ## Building the frontend
@@ -25,29 +26,49 @@ Uses [jQuery](https://jquery.com/) for browser DOM interaction,
 * After you change files in `src` directory run
 
    ```
-   yarn build
+   yarn dev
    ```
+   which will start a webserver on port 9080 and auto-reloads
+   whenever you edit files. Configuration in `rollup.config.js`.
+
+## Testing
 
-* Start a webserver on port 8000 to preview changes
+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).
+
+
+* Run integration test suite (configuration in `.mocharc.json`)
 
    ```
-   yarn start
+   yarn test
+   API_ON_SAME_PORT=1 yarn test
    ```
 
-* Run code style check
+   Setting API_ON_SAME_PORT simulates having both the API and UI on the same server
+   port. That's a rare setup but something https://nominatim.openstreetmap.org/ does
+   so worth testing.
+
+   To run a single test file only
+
+   ```
+   yarn run rollup -c && yarn run mocha test/details.js
+   ```
+
+* Run syntax linter (configuration in `.eslint.json`)
 
    ```
    yarn lint
    ```
 
+
 ## Prepare a release
 
 1. Update version number in `package.json` file
 
 2. Update `CHANGES.md` file
 
-3. Commit your changes: `git add... `, `git commit ...`, `git push ...` etc
+3. Commit your changes: `git add ... `, `git commit ...`, `git push ...` etc
 
 4. Tag release: `git tag THE_VERSION_NUMBER`, `git push --tags`
 
-5. Upload release
\ No newline at end of file
+5. Create release on https://github.com/osm-search/nominatim-ui/releases
+   This (a triggered Github Action) will run `yarn build` and add the `dist/build/bundle.*` files.