The OpenStreetMap Community Index is designed to show people what community groups there are within OpenStreetMap, in any part of the world. If I look near me I see a local pub meeting (sadly on hold during the pandemic), some country-level resources, and then international resources.

On a couple of occasions I’ve seen things that are missing or need updating, and this diary entry is designed to complement the existing documentation to describe what needs to be done to fix that.

Creating a local copy

In my case I already have a fork of https://github.com/osmlab/osm-community-index at https://github.com/SomeoneElseOSM/osm-community-index. There’s a “fork” button in the top right of Github’s UI that allows you to do this.

Next, I’ll create a local branch to work on. The default branch at https://github.com/SomeoneElseOSM/osm-community-index is “main” and the UI will say “This branch is even with osmlab:main.” because (in your case) you’ve only just created it. In github’s branch selector just type the name of the new branch to create. In this case I created “add_forum_at_world_level”, because I noticed that there wasn’t a link to the OSM Forum at the international level, although there are many links to country-level forums from the community index.

Next, “git clone” your repository wherever it is you want to work. I’m working on a completely new virtual machine to do this, so I have to take a slight detour first - see “setting up ssh access to github” below. Once that’s done:

mkdir ~/src
cd ~/src
git clone git@github.com:SomeoneElseOSM/osm-community-index.git
git checkout add_forum_at_world_level

Note that I’ve used a version of “git clone” that is designed to work with ssh. Github is (rightly) moving away from password-based verification and will send you a warning email if you try and use a password during the transfer period.

To make sure that everything works before making any changes, we’ll build everything as it currently stands. The machine I’m running on is a virtual server running Ubuntu 20.04 LTS. It’s actually set up as per here so it already has Apache2 and some node.js software on it. The versions of node.js and npm are the defaults for this version of Ubuntu, and are:

node -v
v10.19.0
npm -v
6.14.4

An older OS with and older version of node.js or npm may struggle, and I’m not going into detail about node.js versions or package managers here, because it’s way above my pay grade.

cd ~/src/osm-community-index
npm install
npm run test

That checks that everything is OK. To build as is:

npm run build
npm run dist

That creates various files in e.g. ~/src/osm-community-index/dist/ including “completeFeatureCollection.min.json” (in previous versions called “combined.min.geojson”), which is all the data needed by the website as it runs. On my server “/var/www/html” is the root of the website. To copy the files into there:

sudo mkdir /var/www/html/community
sudo cp ~/src/osm-community-index/docs/index.html /var/www/html/community/
sudo cp ~/src/osm-community-index/dist/completeFeatureCollection.min.json /var/www/html/community/

Next, we’ll need to edit the “index” file on the web site so that it refers to the local “completeFeatureCollection.min.json”, not one from an external webserver.

sudo nano /var/www/html/community/index.html

In my case I’ll edit it so that:

var dataURL = 'http://192.168.1.66/community/completeFeatureCollection.min.json';

and restart apache:

sudo /etc/init.d/apache2 restart

If I browse to http://192.168.1.66/community/ the site looks exactly like the real one.

Adding a new feature

Next, we’ll make a change. This document describes the format in detail. In my case I want to create a “resource” at world level (“OpenStreetMap Forum”) but don’t need to create a “feature” since my new resource is worldwide.

If you think you might have to add a feature please check https://ideditor.codes first (iD and the community index share this). It is quite possible that your region may be already listed, since quite a few unusual values are already there. There are a couple of other caveats to be aware of as well.

I created my new .json file based on one of the other international examples. For “languageCodes” I chose “en” because most (though not all) of the posts at supranational level are in English. “contacts” is a bit complicated, since there are many top-level OSM forums and they don’t all have the same admins. I chose an address that I knew would at least result in messages being passed on to the right admin(s). For “order” I chose “something in the middle of the list”. The current top-level order settings are:

Facebook  3
Reddit    2
Discord   unset
Telegram  unset
Twitter   unset
OSMF      unset
Help      -2
IRC       -4

Given OSMF’s FOSS policy, I’m not convinced that Facebook should be at the top of that list, but that’s another issue for another time. Once all changes have been made, build again:

npm run build

Any errors with field contents should be displayed here. Fix this and run “npm run build” again before continuing. When complete:

npm run dist
sudo cp ~/src/osm-community-index/dist/completeFeatureCollection.min.json /var/www/html/community/
sudo /etc/init.d/apache2 restart

Now, when I browse to http://192.168.1.66/community/ the new entry appears. We’re ready to check in the changes. The current status of things can be seen via:

git status

To check in:

git add resources/world/OSM-Forum.json
git add .
git commit

“git commit” does a local update from “files you have edited locally” to “your local copy of the git repository on this server”. Next:

git push

That updates your github copy of the community index with the copy from your local server.

At this point, the branch in my github account says “This branch is 1 commit ahead of osmlab:main.” when I browse to it.

Creating a pull request

There’s an option from there to create a pull request, which is saying to the maintainers of https://github.com/osmlab/osm-community-index “hello, I think it’d be a great idea if you made this change”. There’s no guarantee that it’ll be accepted (there may be a good reason that I’m unaware of why that resource isn’t listed at https://openstreetmap.community/). If/when it does get accepted it’ll look something like this.

Setting up ssh access to github

As an aside, because this is the first time that I’ve needed to use this machine for anything ssh-related, I’ll create ssh keys and upload to github.

cd ~/
ls .ssh
ls: cannot access '.ssh': No such file or directory

To create a key pair:

ssh-keygen -t ed25519 -C "anemailaddress@example.com"

You’ll be asked for a passphrase - enter one and verify it. A file, in my case called “~/.ssh/id_ed25519.pub” will be created that begins “ssh-ed25519”.

In Github:

Settings
ssh and gpg keys
New SSH Key

Add ssh key
(confirm password)
(receive email about new ssh key)

When you get to the “git commit” part, if this is the first time that you’ve done that on this machine, you may be asked to “Please tell me who you are” and suggested to run:

git config --global user.email "you@example.com"
git config --global user.name "Your Name"