Including this README overhaul as part of OpenHistoricalMap/issues#786.

README.md

@@ -1,39 +1,57 @@
-# overpass turbo
+# The OpenHistoricalMap fork of overpass-turbo
 
-- https://overpass-turbo.eu/ – stable version
-- https://tyrasd.github.io/overpass-turbo/ – latest version
+This is the OpenHistoricalMap (OHM) fork of [overpass-turbo](https://github.com/tyrasd/overpass-turbo). It's a workbench for crafting & running queries using the [Overpass-API](https://wiki.openstreetmap.org/wiki/Overpass_API/Overpass_QL) and the [OHM extensions](https://wiki.openstreetmap.org/wiki/OpenHistoricalMap/Overpass) to that API. It can be seen in operation at [https://overpass-turbo.openhistoricalmap.org/](https://overpass-turbo.openhistoricalmap.org/) where a number of example queries are included under the __Load__ button.
 
-This is a GUI for testing and developing queries for the [Overpass-API](http://www.overpass-api.de/). It can also used for simple analysis of OSM data.
+![ohm_overpass_turbo_screenshot.png](ohm_overpass_turbo_screenshot.png)
 
-[![](https://upload.wikimedia.org/wikipedia/commons/thumb/0/0c/Overpass_turbo_screenshot_2022.png/1280px-Overpass_turbo_screenshot_2022.png)](https://overpass-turbo.eu)
+Our philosophy is to stay as close to the upstream version as possible with modifications limited to the time dimension that differentiates OHM from OpenStreetMap (OSM). Most apparent in this code base is our use of [MapLibre GL JS](https://github.com/maplibre/maplibre-gl-js) in combination with [maplibre-gl-leaflet
+](https://github.com/maplibre/maplibre-gl-leaflet) to shoehorn OHM-results into a basemap created with Leaflet. We include upstream documentation (README, LICENSE, etc.) in [`./upstream/`](./upstream/) and note OHM-specifics in this README.
 
-## Getting Started
+## Development
 
-Just point your browser to [overpass-turbo.eu](http://overpass-turbo.eu) and start running your Overpass queries.
+### Quick start
 
-More information about _overpass turbo_ is found in the [OSM wiki](http://wiki.openstreetmap.org/wiki/Overpass_turbo).
+1. `yarn install`
+2. `yarn run start` for a Development server listening at http://localhost:5173
+3. `yarn run build` for a minified build in `./dist`
 
-## Translating
+### git-branches
 
-Translations are managed using the [Transifex](https://www.transifex.com/projects/p/overpass-turbo) platform. After signing up, you can go to [overpass-turbo's project page](https://www.transifex.com/projects/p/overpass-turbo), select a language and click _Translate now_ to start translating.
+As with all OHM projects, issues are filed in [the standalone Issues repository](https://github.com/OpenHistoricalMap/issues). Development is typically carried out on feature branches created from our `main` branch and merged via Pull Requests.
 
-If your language isn't currently in the list, just drop me a [mail](mailto:[email protected]) or open an [issue ticket](https://github.com/tyrasd/overpass-turbo/issues/new).
+The `master` branch is deprecated and will be removed.
 
-To download the latest translations from Transifex, run `tx pull --all` using the [Transifex client `tx`](https://docs.transifex.com/client/introduction).
+### Gotchas
 
-## Development
+Upstream `overpass-turbo` makes extensive use of `localStorage`. If your code alterations are not being picked up, you may want to go beyond clearing your browser cache to wiping out `localStorage` using your JavaScript developer tools.
 
-### URL parameters
+## Translations
 
-_overpass turbo_ can be linked from other applications by using [URL parameters](http://wiki.openstreetmap.org/wiki/Overpass_turbo/Development#URL_Parameters).
-For example, one can provide a query to load, set the initial map location, or instruct turbo to load a [template](http://wiki.openstreetmap.org/wiki/Overpass_turbo/Templates).
+overpass-turbo translations that are not specific to OHM–__and that is most of them!__–should be submitted via the upstream system at [Transifex](https://www.transifex.com/projects/p/overpass-turbo). Our limited need for translation is handled by [translatewiki.net](https://translatewiki.net/wiki/Special:Translate/ohm-overpass-turbo).
 
-### git-branches
 
-Development is done in the _master_ branch, stable releases are marked with git tags, the _gh-pages_ branch contains static builds of the releases.
+## Testing
+### Black box
 
-### install & run
+* maps should display OHM data using OHM style & OHM attribution
+* OSM basemaps should not appear, even momentarily
+* query results, permalinks, etc. should link to OHM, not OSM, nodes, ways, and relations
+* query results should include OHM specifics such as `start_date`
+* __Help__ documentation should refer to OHM unless a general OSM document is superior and appropriate
 
-1. `yarn install`
-2. `yarn run start` for a Development server listening at http://localhost:5173
-3. `yarn run build` for a minified build in `./dist`
+### White box
+
+TBD.
+
+
+## Continuous integration
+
+Synchronization with `upstream` is carried out daily using a combination of the [`ohm.upstream-sync`](./.github/workflows/ohm.upstream-sync.yml) GitHub action, the [`upstream_sync`](./scripts/upstream_sync.sh) bash script, and `the-sacrifice` branch which is recreated at each run. This is new as of spring 2024 and is very much a work-in-progress.
+
+## Releases
+
+We began to tag [releases](https://github.com/OpenHistoricalMap/overpass-turbo/releases) in spring 2024. Releases are occasional. Our versioning is independent of upstream.
+
+## Deployment to staging and production
+
+As with all OHM projects, deployment to [staging](https://overpass-turbo-staging.openhistoricalmap.org/) and [production](https://overpass-turbo.openhistoricalmap.org/) environments is carried out via sha manipulation to the corresponding branches in the [ohm-deploy](https://github.com/OpenHistoricalMap/ohm-deploy/blob/main/.github/workflows/frontend-overpass.yaml#L36) repository.