Skip to content

Latest commit

 

History

History
212 lines (166 loc) · 7.82 KB

CONTRIBUTING.md

File metadata and controls

212 lines (166 loc) · 7.82 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 features/ there are .geojson files to describe the areas where the communities are active
  • Under resources/ there are .json files to describe the community resources
tl;dr

To add your community resource:

  • Add a feature .geojson file under features/ folder
    • This is a boundary around where the resource is active
    • You can use geojson.io to create these
  • 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
    • Several resources can share the same .geojson feature
  • npm run test
    • This will build and check for errors and make the files pretty

Features

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

Feature files look like this:

{
  "type": "Feature",
  "id": "usa_full"
  "properties": {},
  "geometry": {
    "type": "MultiPolygon",
    "coordinates": [
      ...
    ]
  }
}

You can use a site like geojson.io to create or modify these .geojson files.

Each feature must have a unique id property, for example usa_full.

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",
  "featureId": "usa_full",
  "type": "slack",
  "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://osmus-slack.herokuapp.com/",
  "url": "https://osmus.slack.com",
  "contacts": [
    {
      "name" : "Barney Rubble",
      "email" : "[email protected]"
    }
  ],
  "events": [
    {
      "id": "sotmus2017",
      "i18n": true,
      "name": "State of the Map US 2017",
      "description": "Join the OpenStreetMap community at State of the Map US in Boulder, Colorado.",
      "where": "Boulder, Colorado, USA",
      "when": "2017-10-20",
      "url": "https://2017.stateofthemap.us/"
    }
  ]
}

Here are the properties that a resource file can contain:

  • id - (required) A unique identifier for the resource
  • featureId - (optional) A unique identifier for the feature. This featureId matches the resource to a .geojson feature. If null, this is a global resource.
  • type - (required) Type of community resource. The following types are supported:
    • "discord"
    • "discourse"
    • "facebook"
    • "forum" - For example, on forum.openstreetmap.org
    • "group" - Generic catchall for anything with a url (such as a local OSM chapter page)
    • "irc" - url should be a clickable web join link, server details can go in description
    • "mailinglist" - url should be a link to the listinfo page, e.g. https://lists.openstreetmap.org/listinfo/talk-us
    • "matrix" - e.g. Riot Chat
    • "meetup"
    • "reddit"
    • "slack" - url should link to the Slack itself, and signupUrl can link to an inviter service (see example above)
    • "telegram"
    • "twitter"
  • name - (required) Display name for this community resource
  • description - (required) One line description of the community resource
  • extendedDescription - (optional) Longer description of the community resource
  • 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

Each community resource must have at least one contact person:

  • 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

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": "sotmus2017",
      "i18n": true,
      "name": "State of the Map US 2017",
      "description": "Join the OpenStreetMap community at State of the Map US in Boulder, Colorado.",
      "where": "Boulder, Colorado, USA",
      "when": "2017-10-20",
      "url": "https://2017.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.