Info for Maintainers - osmlab/name-suggestion-index GitHub Wiki

This page contains useful information for maintainers, including how to clone and build the project.

You don't need to know all of this if you just want to contribute to the index!

• Prerequisites
• Project Setup
• Building the index
• Syncing with Wikidata
• Releasing
• Building nsi.guide
• Other commands
• Collecting names from the OSM planet

 

Prerequisites

This project uses GitHub to track issues and manage our source code.

• Check out the Git Guides to learn more.

This project uses Bun as our development environment.

• Check out the Bun Docs to learn more.
• (It's similar to other JavaScript tools like Node/Jest/Esbuild/Vite, so knowing any of those already will help you a lot).
• Bun supports both JavaScript and TypeScript.

Optional programs

• GitHub Desktop: a visual interface that can be used instead of using git commands
• Visual Studio Code: a powerful IDE that has a built-in terminal to run bun commands

 

Project Setup

If you want to contribute to name-suggestion-index, you'll probably need to:

• Install Bun
• git clone name-suggestion-index
• cd into the project folder
• bun install the dependencies

Updates

• git pull origin --rebase is a good way to keep your local copy of the code updated
• rerun bun install whenever dependencies are updated in package.json

 

Building the index

• bun run build
  • Takes a few seconds and should be run whenever the data/* or config/* files change
  • Processes custom locations under features/**/*.geojson into dist/featureCollection.json
  • Sorts dist/collected/* name lists into dist/filtered/* "keep" and "discard" name lists
  • Merges new items found in the "keep" lists into the data/* files
  • Generates ids
  • Outputs warnings to suggest updates to data/**/*.json
  • Make sure to check in code when done, with something like git add . && git commit -m 'bun run build'

 

Syncing with Wikidata

• bun run wikidata
  • Requires a secrets file
  • Takes about 20 minutes and should be run occasionally to keep NSI in sync with Wikidata
  • Fetches related Wikidata names, descriptions, logos, then updates dist/wikidata.json
  • Updates the Wikidata pages to contain the current NSI identifiers
  • Outputs warnings to suggest fixes on Wikidata for missing social accounts, or other common errors

 

Releasing

• bun run dist
  • Takes about one minute and generates 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
  • 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)

To publish an official release, follow the steps in the Release Checklist.

• 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 (such as Rapid) will appear updated soon after publishing
• Publishing the code to NPM requires rights to run bun publish

 

Testing nsi.guide

https://nsi.guide is a web application written in ReactJS that lets anyone browse the index.

• bun run build:js (or just build)
  • Rebuilds the ReactJS code for https://nsi.guide
  • The source code for this application can be found under nsiguide/*
• bun run start
  • Start the local server, listens on http://127.0.0.1:8080/

 

Other commands

• bun run lint - Checks the Javascript code for correctness
• bun run test - Runs tests agains the Javascript code
• bun run - Lists other available commands

 

Collecting names from the OSM planet

New: This lives over in https://github.com/ideditor/nsi-collector now.

Once nsi-collector publishes a new version:

• Run bun update --save @ideditor/nsi-collector to grab the new version
• Run bun run build to move the collector data into dist/
• Attempt a bun 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 bun run build until the duplicate id issues are gone.