From d0721aae8ba1f073a31b907eb0a2c648678f5847 Mon Sep 17 00:00:00 2001 From: Bryan Housel Date: Tue, 16 Mar 2021 12:01:29 -0400 Subject: [PATCH] Refresh docs --- CONTRIBUTING.md | 125 +++++++++++++++-------------------------- DEVELOPING.md | 44 +++++++++++++++ LICENSE.md | 2 +- MAINTAINING.md | 100 +++++++++++++++++++++++++++++++++ README.md | 144 ++++++++++++------------------------------------ RELEASE.md | 11 ++-- WARNINGS.md | 40 ++++++++++++++ 7 files changed, 271 insertions(+), 195 deletions(-) create mode 100644 DEVELOPING.md create mode 100644 MAINTAINING.md create mode 100644 WARNINGS.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index debea9dd3..79b8a0bf5 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,39 +2,51 @@ ### tl;dr -##### :raising_hand:   How to help: +##### 🙋‍♀️   How to help: -* [Prerequisites & installation instruction in the README](https://github.com/osmlab/name-suggestion-index#prerequisites) + * `npm run build` will reprocess the files and output warnings -* Resolve warnings - [show me](#thinking--resolve-warnings) * Remove generic names - [show me](#hocho--remove-generic-names) * Add `brand:wikidata` and `brand:wikipedia` tags - [show me](#female_detective--add-wiki-tags) * Add missing brands - [show me](#convenience_store--add-missing-brands) * Edit Wikidata in compliance with their policies - [show me](#memo--edit-wikidata) -Tip: You can browse the index at https://nsi.guide/ -to see which brands are missing Wikidata links, or have incomplete Wikipedia pages. +👉 Tip: You can browse the index at https://nsi.guide/ to see which brands are missing Wikidata links, or have incomplete Wikipedia pages. -##### :no_entry_sign:   Don't edit the files in `dist/` - they are generated: +#### Source files (edit these): -* `dist/collected/*` - all the frequent names and tags collected from OpenStreetMap -* `dist/filtered/*` - subset of names and tags that we are keeping or discarding -* `dist/wikidata.json` - cached brand data retrieved from Wikidata +The files under `config/*`, `data/*`, and `features/*` can be edited: -##### :white_check_mark:   Do edit the files in `config/`, `data/`, and `features/`: +- `data/*` - Data files for each feature category, organized by topic and OpenStreetMap tag + - `brands/**/*.json` + - `flags/**/*.json` + - `operators/**/*.json` + - `transit/**/*.json` -* `config/*`: - * `config/genericWords.json` - Regular expressions used to find and discard generic names - * `config/matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching - * `config/replacements.json` - Mapping of old Wikidata QIDs map to their replacement new Wikidata and Wikipedia values. - * `config/trees.json` - Metadata about subtrees in this project, and regular expressions used to keep and discard tags -* `data/*` - Data files for each kind of branded business, organized by topic and OpenStreetMap tag - * `data/brands/amenity/*.json` - * `data/brands/leisure/*.json` - * `data/brands/shop/*.json` - * and so on... -* `features/*` - Source files for custom locations where brands are active +- `features/*` - GeoJSON files that define custom regions (aka [geofences](https://en.wikipedia.org/wiki/Geo-fence)) + - `us/new_jersey.geojson` + - `ca/quebec.geojson` + - and so on… + +- `config/*` + - `genericWords.json` - Regular expressions used to find and discard generic names + - `matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching + - `replacements.json` - Mapping of old Wikidata QIDs to replacement new Wikidata/Wikipedia values + - `trees.json` - Metadata about subtrees supported in this project + + +#### Generated files (do not edit): + +The files under `dist/*` are generated: +- `dist/nsi.json` - The complete index +- `dist/dissolved.json` - List of items that we believe may be dissolved based on Wikidata claims +- `dist/taginfo.json` - List of all tags this project supports (see: https://taginfo.openstreetmap.org/) +- `dist/wikidata.json` - Cached data retrieved from Wikidata (names, social accounts, logos) +- `dist/collected/*` - Frequently occuring tags collected from OpenStreetMap +- `dist/config/*` - A copy of the config files (see below) +- `dist/filtered/*` - Subset of tags that we are keeping or discarding +- `dist/presets/*` - Preset files generated for iD and JOSM editors   @@ -42,8 +54,7 @@ to see which brands are missing Wikidata links, or have incomplete Wikipedia pag ### :world_map:   About OpenStreetMap -[OpenStreetMap](https://openstreetmap.org) is a free, editable map of the whole world that -is being built by volunteers. +[OpenStreetMap](https://openstreetmap.org) is a free, editable map of the whole world that is being built by volunteers. Features on the map are defined using _tags_. Each tag is a `key=value` pair of text strings. For example, a McDonald's restaurant might have these tags: @@ -58,9 +69,13 @@ For example, a McDonald's restaurant might have these tags: ### :bulb:   About the name-suggestion-index -The goal of this project is to define the _most correct tags_ to assign to each common brand name. -This helps people contribute to OpenStreetMap, because they can pick "McDonald's" from a list -and not need to worry about the tags being added. +The goal of this project is to define the _most correct tags_ for common features, +and to link these features to a [Wikidata](https://www.wikidata.org/) QID identifer. + +- This helps people contribute to OpenStreetMap, because they can pick "McDonald's" +from a list and not need to worry about the tags being added. +- This helps the OpenStreetMap project because consumers can use and understand the +data better when it is tagged consistently.   @@ -240,7 +255,7 @@ This project includes a "fuzzy" matcher that can match alternate names and tags … ``` -:point_right: The matcher code also has some useful automatic behaviors... +👉 The matcher code also has some useful automatic behaviors… You don't need to add `matchNames` for: - Name variations in capitalization, punctuation, spacing (the middots common in Japanese names count as punctuation, so "V・ドラッグ" already matches "vドラッグ") @@ -264,23 +279,15 @@ You can optionally add a `note` property to any item. The note can contain any The notes just stay with the name-suggestion-index; they aren't OpenStreetMap tags or used by other software. ```js -"path": "brands/amenity/bank", -"items": [ - … { "displayName": "United Bank (Connecticut)", "id": "unitedbank-28419b", "locationSet": { "include": ["peoples_united_bank_ct.geojson"] }, "note": "Merged into People's United Bank (Q7165802) in 2019, see https://en.wikipedia.org/wiki/United_Financial_Bancorp", "tags": { - "amenity": "bank", - "brand": "United Bank", - "brand:wikidata": "Q16959074", - "brand:wikipedia": "en:United Financial Bancorp", - "name": "United Bank" + … } }, - … ```   @@ -295,7 +302,6 @@ You should also give each entry a unique `displayName`, so everyone can tell the ```js - … { "displayName": "Price Chopper (Kansas City)", "id": "pricechopper-9554e9", @@ -320,7 +326,6 @@ You should also give each entry a unique `displayName`, so everyone can tell the "shop": "supermarket" } }, - … ```   @@ -338,7 +343,7 @@ Feature files look like this: "properties": {}, "geometry": { "type": "Polygon", - "coordinates": [...] + "coordinates": […] } } ``` @@ -365,46 +370,6 @@ To rebuild the index, run: This will output a lot of warnings, which you can help fix! -  - -### :thinking:   Resolve warnings - -Warnings mean that you need to edit files under `data/brands/*`. -The warning output gives a clue about how to fix or suppress the warning. -If you aren't sure, just ask on GitHub! - -  - -#### Duplicate names - -``` - Warning - Potential duplicate: ------------------------------------------------------------------------------------------------------- - If the items are two different businesses, - make sure they both have accurate locationSets (e.g. "us"/"ca") and wikidata identifiers. - If the items are duplicates of the same business, - add `matchTags`/`matchNames` properties to the item that you want to keep, and delete the unwanted item. - If the duplicate item is a generic word, - add a filter to config/genericWords.json and delete the unwanted item. ------------------------------------------------------------------------------------------------------- - "shop/supermarket|Carrefour" -> duplicates? -> "amenity/fuel|Carrefour" - "shop/supermarket|VinMart" -> duplicates? -> "shop/department_store|VinMart" -``` - -_What it means:_ These names are commonly tagged differently in OpenStreetMap. This might be ok, but it might be a mistake. - -For "VinMart" we really prefer for it to be tagged as a supermarket. It's a single brand frequently mistagged. -* Add `"matchTags": ["shop/department_store"]` to the (preferred) `"shop/supermarket|VinMart"` entry -* Delete the (not preferred) entry for `"shop/department_store|VinMart"` - -For "Carrefour" we know that can be both a supermarket and a fuel station. It's two different things. -* Make sure both items have a `brand:wikidata` tag and appropriate `locationSet`. - -Existing tagging (you can compare counts in `dist/filtered/names_keep.json`), information at the relevant Wikipedia page or the company's website, and [OpenStreetMap Wiki tag documentation](https://wiki.openstreetmap.org/wiki/Map_Features) all help in deciding how to address duplicate warnings. - -If the situation is unclear, one may contact the [local community](https://community.osm.be/) and ask for help. - -  ### :hocho:   Remove generic names @@ -621,7 +586,7 @@ is a valuable way to get ahead of incorrect tagging. 4. If instances of this brand are commonly mistagged add the `"matchNames": []` key to list these. Again, refer to [here](#card_file_box--about-the-data-files) for syntax. -5. Run `npm run build` and resolve any [duplicate name warnings](#thinking--resolve-warnings). +5. Run `npm run build`   diff --git a/DEVELOPING.md b/DEVELOPING.md new file mode 100644 index 000000000..f296cdc20 --- /dev/null +++ b/DEVELOPING.md @@ -0,0 +1,44 @@ +## Info for Developers + +This file contains useful information for developers who want to use the name-suggestion-index in another project. + + +### Downloading the index files + +You can download the files from the index directly from GitHub or use a CDN. + +#### Latest published release (stable forever): + +Direct from GitHub ([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent)): +```js +https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file} +https://raw.githubusercontent.com/osmlab/name-suggestion-index/v5.0.20210315/dist/name-suggestions.presets.min.xml +``` + +Via JSDelivr CDN ([docs](https://www.jsdelivr.com/)): +```js +https://cdn.jsdelivr.net/npm/name-suggestion-index@{semver}/{path to file} +https://cdn.jsdelivr.net/npm/name-suggestion-index@5.0/dist/name-suggestions.presets.min.xml +``` + +#### Current development version (breaks sometimes!): + +Direct from GitHub ([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent)): +```js +https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file} +https://raw.githubusercontent.com/osmlab/name-suggestion-index/main/dist/presets/nsi-josm-presets.min.xml +``` + +Via JSDelivr CDN ([docs](https://www.jsdelivr.com/?docs=gh)): +```js +https://cdn.jsdelivr.net/gh/name-suggestion-index@{branch or tag}/{path to file} +https://cdn.jsdelivr.net/gh/osmlab/name-suggestion-index@main/dist/presets/nsi-josm-presets.min.xml +``` + + +### Code + +Some of the JavaScript code is available in both ES6 module (.mjs) and CommonJS (.js) formats. + +More info soon. + diff --git a/LICENSE.md b/LICENSE.md index 4e7e8de7b..b066e5651 100644 --- a/LICENSE.md +++ b/LICENSE.md @@ -1,4 +1,4 @@ -Copyright 2018, name-suggestion-index contributors +Copyright 2021, name-suggestion-index contributors Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met: diff --git a/MAINTAINING.md b/MAINTAINING.md new file mode 100644 index 000000000..3d331c768 --- /dev/null +++ b/MAINTAINING.md @@ -0,0 +1,100 @@ +## Info For Maintainers + +This file contains useful information for maintainers. +You don't need to know any of this if you just want to contribute to the index! + + +### Prerequisites + +- [Node.js](https://nodejs.org/) version 10 or newer +- [`git`](https://www.atlassian.com/git/tutorials/install-git/) for your platform + + +### Installing + +- Clone this project, for example: + `git clone git@github.com:osmlab/name-suggestion-index.git` +- `cd` into the project folder, +- Run `npm install` to install libraries + + +### Updates + +- `git pull origin --rebase` is a good way to keep your local copy of the index updated +- rerun `npm install` after dependencies are updated in `package.json` + + +### Building the index + +- `npm run build` + - Takes a few seconds and should be run whenever any of the `data/*` or `config/*` files change + - Make sure to check in code when done, with something like `git add . && git commit -m 'npm run build'` + - Processes any custom locations under `features/**/*.geojson` + - Regenerates `dist/filtered/*` keep and discard lists + - Any new items from the keep list not already present in the index will be merged into it + - Outputs many warnings to suggest updates to `data/**/*.json` + + +### Syncing with Wikidata + +- `npm run wikidata` + - Takes about 15 minutes and should be run occasionally to keep NSI in sync with Wikidata + - Make sure to check in code when done, with something like `git add . && git commit -m 'npm run wikidata'` + - Fetches related Wikidata names, descriptions, logos, then updates `dist/wikidata.json` + - Updates the Wikidata pages to contain the current NSI identifiers + - Outputs many warnings to suggest fixes on Wikidata for missing social accounts, or other common errors + - (We may try to automate more of this eventually) + + +### Releasing + +- `npm run dist` + - Takes a few seconds and builds all the files in `dist/*` + - The semantic version number of the project is updated automatically: `major.minor.patch` where patch is the date in `yyyymmdd` format + - Make sure to check in code when done, with something like `git add . && git commit -m 'npm run dist'` + - Rebuilds iD and JOSM presets, taginfo file, other output files + - Should be run whenever the index is in a good state (build and wikidata sync has happened successfully) + - Projects which pull NSI data from GitHub (such as ) will appear updated soon after `npm run dist` + - Other downstream projects may pull from `dist/*` too + +To publish an official release, follow the steps in [RELEASE.md](RELEASE.md). + - Official releases are stable forever and available via NPM or on CDNs like JSDelivr + - Projects which pull name-suggestion-index from NPM or a CDN (sucn as iD) will appear updated soon after publishing + - Publishing the code to NPM requires rights to run `npm publish` + + +### Building nsi.guide + + is a web application written in ReactJS that lets anyone browse the index. + +- `npm run appbuild` + - Rebuilds the ReactJS code for + - The source code for this app can be found under `app/*` + - Only need to rebuild this when the app code changes, not when the index changes. + + +### Other commands + +- `npm run lint` - Checks the Javascript code for correctness +- `npm run test` - Runs tests agains the Javascript code +- `npm run` - Lists other available commands + + +### Collecting names from the OSM planet + +This takes a long time and a lot of disk space. It can be done occasionally by project maintainers. + +- Install `osmium` command-line tool and node package (may only be available on some environments) + - `apt-get install osmium-tool` or `brew install osmium-tool` or similar + - `npm install --no-save osmium` +- [Download the planet](http://planet.osm.org/pbf/) + - `curl -L -o planet-latest.osm.pbf https://planet.openstreetmap.org/pbf/planet-latest.osm.pbf` +- Prefilter the planet file to only include named items with keys we are looking for: + - `osmium tags-filter planet-latest.osm.pbf -R name,brand,operator,network -o filtered.osm.pbf` +- Run `node scripts/collect_all.js /path/to/filtered.osm.pbf` + - results will go in `dist/collected/*.json` +- A new challenge: + - Attempt an `npm run build`. Now that unique `id` properties are generated, it is possible that this command will fail. + - This can happen if there are *multiple* new items that end up with the same `id` (e.g. "MetroBus" vs "Metrobus") + - You'll need to just pick one to keep, then keep trying to run `npm run build` until the duplicate `id` issues are gone. + - `git add . && git commit -m 'Collected common names from latest planet'` diff --git a/README.md b/README.md index 1bd3d763a..73f336e57 100644 --- a/README.md +++ b/README.md @@ -1,10 +1,11 @@ [![build](https://github.com/osmlab/name-suggestion-index/workflows/build/badge.svg)](https://github.com/osmlab/name-suggestion-index/actions?query=workflow%3A%22build%22) [![npm version](https://badge.fury.io/js/name-suggestion-index.svg)](https://badge.fury.io/js/name-suggestion-index) -## name-suggestion-index +## name-suggestion-index (aka "NSI") Canonical features for OpenStreetMap + ### What is it? The goal of this project is to maintain a [canonical](https://en.wikipedia.org/wiki/Canonicalization) @@ -12,9 +13,11 @@ list of commonly used features for suggesting consistent spelling and tagging in [Watch the video](https://2019.stateofthemap.us/program/sat/mapping-brands-with-the-name-suggestion-index.html) from our talk at State of the Map US 2019 to learn more about this project! + ### Browse the index -You can browse the index at . +👉 You can browse the index at . + ### How it's used @@ -40,74 +43,50 @@ Currently used in: - [osmfeatures](https://github.com/westnordost/osmfeatures) - [Go Map!!](https://github.com/bryceco/GoMap) + ### About the index -#### Generated files (do not edit): +You can learn more from these pages: +- - Browse and search all the data +- [CONTRIBUTING.md](CONTRIBUTING.md) - How to contribute data about brands, transit, and other features to this index +- [DEVELOPING.md](DEVELOPING.md) - If you are a developer and want to use the name-suggestion-index in your project +- [MAINTAINING.md](MAINTAINING.md) - How to setup and build the index, sync with wikidata, and make releases -The files under `dist/*` are generated: -* `dist/nsi.json` - The complete index -* `dist/dissolved.json` - List of items that we believe may be dissolved based on Wikidata claims -* `dist/taginfo.json` - List of all tags this project supports (see: https://taginfo.openstreetmap.org/) -* `dist/wikidata.json` - Cached data retrieved from Wikidata -* `dist/collected/*` - Frequently occuring tags collected from OpenStreetMap -* `dist/config/*` - A copy of the config files (see below) -* `dist/filtered/*` - Subset of tags that we are keeping or discarding -* `dist/presets/*` - Preset files generated for iD and JOSM editors #### Source files (edit these): The files under `config/*`, `data/*`, and `features/*` can be edited: -* `config/*`: - * `config/genericWords.json` - Regular expressions used to find and discard generic names - * `config/matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching - * `config/replacements.json` - Mapping of old Wikidata QIDs map to their replacement new Wikidata and Wikipedia values. - * `config/trees.json` - Metadata about subtrees in this project, and regular expressions used to keep and discard tags -* `data/*` - Data files for each kind of feature, organized by topic and OpenStreetMap tag - * `data/brands/**/*.json` - * `data/flags/**/*.json` - * `data/operators/**/*.json` - * `data/transit/**/*.json` - * and so on… -* `features/*` - GeoJSON files that define custom regions where the features are allowed - * `features/us/new_jersey.geojson` - * `features/ca/quebec.geojson` - * and so on… +- `data/*` - Data files for each feature category, organized by topic and OpenStreetMap tag + - `brands/**/*.json` + - `flags/**/*.json` + - `operators/**/*.json` + - `transit/**/*.json` -:point_right: See [CONTRIBUTING.md](CONTRIBUTING.md) for info about how to contribute to this index. +- `features/*` - GeoJSON files that define custom regions (aka [geofences](https://en.wikipedia.org/wiki/Geo-fence)) + - `us/new_jersey.geojson` + - `ca/quebec.geojson` + - and so on… + +- `config/*`: + - `genericWords.json` - Regular expressions used to find and discard generic names + - `matchGroups.json` - Groups of OpenStreetMap tags that are considered equivalent for purposes of matching + - `replacements.json` - Mapping of old Wikidata QIDs to replacement new Wikidata/Wikipedia values + - `trees.json` - Metadata about subtrees supported in this project -#### Downloading the index files: +#### Generated files (do not edit): -You can download the files from the index directly from GitHub or use a CDN. +The files under `dist/*` are generated: +- `dist/nsi.json` - The complete index +- `dist/dissolved.json` - List of items that we believe may be dissolved based on Wikidata claims +- `dist/taginfo.json` - List of all tags this project supports (see: https://taginfo.openstreetmap.org/) +- `dist/wikidata.json` - Cached data retrieved from Wikidata (names, social accounts, logos) +- `dist/collected/*` - Frequently occuring tags collected from OpenStreetMap +- `dist/config/*` - A copy of the config files (see below) +- `dist/filtered/*` - Subset of tags that we are keeping or discarding +- `dist/presets/*` - Preset files generated for iD and JOSM editors -##### Latest published release (stable forever): - -Direct from GitHub ([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent)): -```js -https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file} -https://raw.githubusercontent.com/osmlab/name-suggestion-index/v4.0.2/dist/name-suggestions.presets.min.xml -``` - -Via JSDelivr CDN ([docs](https://www.jsdelivr.com/)): -```js -https://cdn.jsdelivr.net/npm/name-suggestion-index@{semver}/{path to file} -https://cdn.jsdelivr.net/npm/name-suggestion-index@4.0.2/dist/name-suggestions.presets.min.xml -``` - -##### Current development version (breaks sometimes!): - -Direct from GitHub ([docs](https://stackoverflow.com/questions/39065921/what-do-raw-githubusercontent-com-urls-represent)): -```js -https://raw.githubusercontent.com/osmlab/name-suggestion-index/{branch or tag}/{path to file} -https://raw.githubusercontent.com/osmlab/name-suggestion-index/main/dist/presets/nsi-josm-presets.min.xml -``` - -Via JSDelivr CDN ([docs](https://www.jsdelivr.com/?docs=gh)): -```js -https://cdn.jsdelivr.net/gh/name-suggestion-index@{branch or tag}/{path to file} -https://cdn.jsdelivr.net/gh/osmlab/name-suggestion-index@main/dist/presets/nsi-josm-presets.min.xml -``` ### Participate! @@ -117,57 +96,6 @@ https://cdn.jsdelivr.net/gh/osmlab/name-suggestion-index@main/dist/presets/nsi-j We're always looking for help! If you have any questions or want to reach out to a maintainer, ping `bhousel` on: - [OpenStreetMap US Slack](https://slack.openstreetmap.us/) (`#poi` or `#general` channels) -#### Prerequisites - -- [Node.js](https://nodejs.org/) version 10 or newer -- [`git`](https://www.atlassian.com/git/tutorials/install-git/) for your platform - -#### Installing - -- Clone this project, for example: - `git clone git@github.com:osmlab/name-suggestion-index.git` -- `cd` into the project folder, -- Run `npm install` to install libraries - -#### Building the index - -- `npm run build` - - Processes any custom locations under `features/**/*.geojson` - - Regenerates `dist/filtered/*` keep and discard lists - - Any new items from the keep list not already present in the index will be merged into it - - Outputs many warnings to suggest updates to `data/**/*.json` - -#### Building nsi.guide - - is a web application written in ReactJS that lets anyone browse the index. -* The source code for this app can be found under `app/*` -* `npm run appbuild` will rebuild it. - -#### Other commands - -- `npm run wikidata` - Fetch useful data from Wikidata - labels, descriptions, logos, etc. -- `npm run dist` - Rebuild and minify the generated files in the `dist/` folder. -- `npm run` - Lists other available commands - -#### Collecting names from planet - -This takes a long time and a lot of disk space. It can be done occasionally by project maintainers. -You do not need to do these steps in order to contribute to the index. - -- Install `osmium` command-line tool and node package (may only be available on some environments) - - `apt-get install osmium-tool` or `brew install osmium-tool` or similar - - `npm install --no-save osmium` -- [Download the planet](http://planet.osm.org/pbf/) - - `curl -L -o planet-latest.osm.pbf https://planet.openstreetmap.org/pbf/planet-latest.osm.pbf` -- Prefilter the planet file to only include named items with keys we are looking for: - - `osmium tags-filter planet-latest.osm.pbf -R name,brand,operator,network -o filtered.osm.pbf` -- Run `node scripts/collect_all.js /path/to/filtered.osm.pbf` - - results will go in `dist/collected/*.json` -- A new challenge: - - Attempt an `npm run build`. Now that unique `id` properties are generated, it is possible that this command will fail. - - This can happen if there are *multiple* new items that end up with the same `id` (e.g. "MetroBus" vs "Metrobus") - - You'll need to just pick one to keep, then keep trying to run `npm run build` until the duplicate `id` issues are gone. - - `git add . && git commit -m 'Collected common names from latest planet'` ### License diff --git a/RELEASE.md b/RELEASE.md index d3ac15192..4ba06f86e 100644 --- a/RELEASE.md +++ b/RELEASE.md @@ -1,14 +1,13 @@ ## Release Checklist -#### Update version, tag, and publish +### Update version, tag, and publish - [ ] git checkout main - [ ] git pull origin - [ ] npm install - [ ] npm run build -- [ ] Update version number in `package.json` and `README.md` - [ ] npm run wikidata -- [ ] npm run dist -- [ ] git add . && git commit -m 'vA.B.C' -- [ ] git tag vA.B.C -- [ ] git push origin main vA.B.C +- [ ] npm run dist _(version number updates automatically and will print to console)_ +- [ ] git add . && git commit -m 'A.B.C' +- [ ] git tag A.B.C +- [ ] git push origin main A.B.C - [ ] npm publish diff --git a/WARNINGS.md b/WARNINGS.md new file mode 100644 index 000000000..28e4f8229 --- /dev/null +++ b/WARNINGS.md @@ -0,0 +1,40 @@ +## Resolving Warnings + +### :thinking:   Resolve warnings + +Warnings mean that you need to edit files under `data/brands/*`. +The warning output gives a clue about how to fix or suppress the warning. +If you aren't sure, just ask on GitHub! + +  + +#### Duplicate names + +``` + Warning - Potential duplicate: +------------------------------------------------------------------------------------------------------ + If the items are two different businesses, + make sure they both have accurate locationSets (e.g. "us"/"ca") and wikidata identifiers. + If the items are duplicates of the same business, + add `matchTags`/`matchNames` properties to the item that you want to keep, and delete the unwanted item. + If the duplicate item is a generic word, + add a filter to config/genericWords.json and delete the unwanted item. +------------------------------------------------------------------------------------------------------ + "shop/supermarket|Carrefour" -> duplicates? -> "amenity/fuel|Carrefour" + "shop/supermarket|VinMart" -> duplicates? -> "shop/department_store|VinMart" +``` + +_What it means:_ These names are commonly tagged differently in OpenStreetMap. This might be ok, but it might be a mistake. + +For "VinMart" we really prefer for it to be tagged as a supermarket. It's a single brand frequently mistagged. +* Add `"matchTags": ["shop/department_store"]` to the (preferred) `"shop/supermarket|VinMart"` entry +* Delete the (not preferred) entry for `"shop/department_store|VinMart"` + +For "Carrefour" we know that can be both a supermarket and a fuel station. It's two different things. +* Make sure both items have a `brand:wikidata` tag and appropriate `locationSet`. + +Existing tagging (you can compare counts in `dist/filtered/names_keep.json`), information at the relevant Wikipedia page or the company's website, and [OpenStreetMap Wiki tag documentation](https://wiki.openstreetmap.org/wiki/Map_Features) all help in deciding how to address duplicate warnings. + +If the situation is unclear, one may contact the [local community](https://community.osm.be/) and ask for help. + +