Skip to content

Latest commit

 

History

History
244 lines (189 loc) · 13.3 KB

CONTRIBUTING.md

File metadata and controls

244 lines (189 loc) · 13.3 KB
Raw

Contributing

If you don't understand the explanation below, feel free to post an Issue to describe your community resources. That page contains some pointers to help you fill in all the info we need. You do need a Github account to be able to post an Issue.

There are 2 kinds of files in this project:

  • Under resources/ there are .json files to describe the community resources
  • Under features/ there are .geojson files to describe the areas where the communities are active
tl;dr

To add your community resource:

  • (required) Add a resource .json file under resources/ folder
    • This contains info about what the resource is (slack, forum, mailinglist, facebook, etc.)
    • You can just copy and change an existing one
    • Each resource needs an includeLocations property to say where it is active.
  • (optional) Add a feature .geojson file under features/ folder
    • This is a boundary around where the resource is active
    • You can use geojson.io or other tools to create these.
  • npm run test
    • This will build and check for errors and make the files pretty

Installing

  • Clone this project, for example: git clone git@github.com:osmlab/osm-community-index.git
  • cd into the project folder,
  • Run npm install to install libraries

Resources

These are *.json files found under the resources/ folder. Each resource file contains a single JSON object with information about the community resource.

Resource files look like this:

{
  "id": "OSM-US-slack",
  "type": "slack",
  "includeLocations": ["us"],
  "countryCodes": ["us"],
  "languageCodes": ["en"],
  "name": "OpenStreetMap US Slack",
  "description": "All are welcome! Sign up at {signupUrl}",
  "extendedDescription": "OpenStreetMap is built by a community of mappers that..."
  "signupUrl": "https://slack.openstreetmap.us/",
  "url": "https://osmus.slack.com",
  "order": 4,
  "contacts": [
    {
      "name" : "Barney Rubble",
      "email" : "b@rubble.com"
    }
  ],
  "events": [
    {
      "id": "sotmus2019",
      "i18n": true,
      "name": "State of the Map US 2019",
      "description": "Join the OpenStreetMap community at State of the Map US in Minneapolis, Minnesota.",
      "where": "Minneapolis, Minnesota",
      "when": "2019-sep-05",
      "url": "https://2019.stateofthemap.us/"
    }
  ]
}

Here are the properties that a resource file can contain:

  • id - (required) A unique identifier for the resource.
  • type - (required) Type of community resource (see below for list).
  • includeLocations - (required) Array of locations where the resource is active. May contain any of these:
  • excludeLocations - (optional) Array of locations to exclude from includeLocations (specified in the same format):
  • name - (required) Display name for this community resource (in English, will be sent to Transifex for translation to other languages)
  • description - (required) One line description of the community resource (in English, will be sent to Transifex for translation to other languages)
  • extendedDescription - (optional) Longer description of the community resource (in English, will be sent to Transifex for translation to other languages)
  • url - (required) A url link to visit the community resource
  • signupUrl - (optional) A url link to sign up for the community resource
  • countryCodes - (optional) Array of two letter country codes where the community is active
  • languageCodes - (optional) Array of two letter or three letter spoken by this community
  • order - (optional) When several resources with same geography are present, this adjusts the display order (default = 0, higher numbers display more prominently)

Each resource must have a type. The following values are supported:

Type Icon Description
aparat An Aparat video channel.
discord A Discord chat channel.
discourse A Discourse forum.
facebook A Facebook group.
forum A generic web forum (e.g. a group on https://forum.openstreetmap.org/).
github A GitHub organization or repository.
group A generic non-OpenStreetMap local group with a url (e.g. Maptime chapter).
irc An IRC channel. url should be a clickable web join link, server details can go in description.
mailinglist A mailing list. url should be a link to the listinfo page, e.g. https://lists.openstreetmap.org/listinfo/talk-us.
matrix A Matrix chat, e.g. Riot Chat.
meetup A Meetup group.
osm A url for an OpenStreetMap group.
osm-lc A url for an official OpenStreetMap Local Chapter.
reddit A subreddit on Reddit.
slack A Slack workspace. url should link to the workspace itself, and signupUrl can link to an inviter service (see example above).
telegram A Telegram channel.
twitter A Twitter account.
url A generic catchall for anything with a url.
wiki An OpenStreetMap wiki project page
youthmappers A YouthMappers chapter.
youtube A YouTube channel.

Each community resource should have at least one contact person. This is optional:

  • name - (required) The contact person's name
  • email - (required) The contact person's email address

Resources may have events. These are optional.

  • i18n - (optional) if true, name, description and where will be translated
  • id - (required if i18n=true) A unique identifier for the event
  • name - (required) Name of the event
  • description - (required) One line description of the event
  • where - (required) Where the event is
  • when - (required) When the event is (Should be a string parseable by Date.parse, and assumed to be local time zone for the event)
  • url - (optional) A url link for the event

Features

These are *.geojson files found under the features/ folder. Each feature file contains a single GeoJSON Feature for a region where a community resource is active.

Feature files look like this:

{
  "type": "Feature",
  "id": "boston_metro",
  "properties": {},
  "geometry": {
    "type": "Polygon",
    "coordinates": [...]
  }
}

Note: A FeatureCollection containing a single Feature is ok too - the build script can handle this.

There are many online tools to create or modify these .geojson files. A workflow could be:

  1. Create the shape with geojson.io from scratch.

or

  1. Generate a precise file with the Polygon creation from an OSM Relation.
  2. Simplify the file with Mapshaper. Beware that the simplification probably cuts some border areas.
  3. So load the file in geojson.io and include the border areas again and perhaps reduce the point count further. It is probably better to have the feature a bit larger than missing an area.

Building

  • Just npm run test
    • This will check the files for errors and make them pretty.

Translations

All community resources automatically support localization of the name, description, and extendedDescription text. These fields should be written in US English.

The description and extendedDescription properties support the following replacement tokens:

  • {url} - Will be replaced with the url
  • {signupUrl} - Will be replaced with the signupUrl

For example: "Sign up at {signupUrl}".

If a resource includes events, you can choose whether to write the name, description, and where fields in your local language, or write in US English and add "i18n": true to allow translation of these values (useful for events with a wider audience).

{
  "id": "OSM-US-Slack",
  "name": "OpenStreetMap US Slack",
  ...
  "events": [
    {
      "id": "sotmus2019",
      "i18n": true,
      "name": "State of the Map US 2019",
      "description": "Join the OpenStreetMap community at State of the Map US in Minneapolis, Minnesota.",
      "where": "Minneapolis, Minnesota",
      "when": "2019-sep-05",
      "url": "https://2019.stateofthemap.us/"
    }
}

Translations are managed using the Transifex platform. After signing up, you can go to iD's project page, select a language and click Translate to start translating.

The translation strings for this project are located in a resource called community.

For maintainers

Transifex will automatically fetch the source file from this repository daily. We need to manually pull down and check in the translation files whenever we make a new release (see RELEASE.md).

To work with translation files, install the Transifex Client software.

The Transifex Client uses a file ~/.transifex.rc to store your username and password.

Note that you can also use a Transifex API Token in place of your username and password. In this usage, the username is api and the password is the generated API token.

Once you have installed the client and setup the ~/.transifex.rc file, you can use the following commands:

  • tx push -s - upload latest source /i18n/en.yaml file to Transifex
  • tx pull -a - download latest translation files to /i18n/<lang>.yaml

For convenience you can also run these commands as npm run txpush or npm run txpull.