Skip to content

Latest commit

 

History

History
260 lines (197 loc) · 13.5 KB

CONTRIBUTING.md

File metadata and controls

260 lines (197 loc) · 13.5 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 custom .geojson files

tl;dr

To add your community resource to the index:

  • Add resource .json files under the resources/ folder
    • Each file contains info about what the resource is (slack, forum, mailinglist, facebook, etc.)
    • Each file also contains info about which locations the resource is active. The locations can be country or region codes, points, or custom .geojson files in the features/* folder.
    • You can copy and change an existing file to get started.
  • run npm run test
    • This will check the files for errors and make them pretty.
    • If you don't have Node installed, you can skip this step and we will do it for you.
  • If there are no errors, submit a pull request.

Installing

  • Clone this project, for example: git clone [email protected]: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",
  "locationSet": { "include": ["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" : "[email protected]"
    }
  ],
  "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.
  • locationSet - (required) Where the community resource is active (see below for details).
  • type - (required) Type of community resource (see below for list).
  • 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
  • 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)
  • contacts - (optional) Contact information for people who are responsible for the resource.
  • events - (optional) Upcoming events that the resource wants to promote (see below for details).

locationSet

Each resource must have a locationSet to define where the resource is active.

"locationSet": {
  "include": [ Array of locations ],   // required
  "exclude": [ Array of locations ]    // optional
}

The "locations" can be any of the following:

  • Codes recognized by the country-coder library. These should be ISO 3166-1 2 or 3 letter country codes or UN M.49 numeric codes.
    Example: "de"
  • Points as [longitude, latitude] coordinate pairs. A 25km radius circle will be computed around the point.
    Example: [8.67039, 49.41882]
  • Filenames for .geojson features. If you want to use your own features, you'll need to add these under the features/ folder. Each Feature must have an id that ends in .geojson.
    Example: "de-hamburg.geojson"
    Tip: You can use geojson.io or other tools to create these.

See location-conflation project for details and examples.

type

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
xmpp An XMPP/Jabber channel. url should be a clickable web join link, server details can go in description.
youthmappers A YouthMappers chapter.
youtube A YouTube channel.

contacts

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

events

Resources may have upcoming 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 optional *.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.geojson",
  "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. Drawing a simple shape with geojson.io works great.

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.