Skip to content

Latest commit

 

History

History
140 lines (105 loc) · 6.25 KB

CONTRIBUTING.md

File metadata and controls

140 lines (105 loc) · 6.25 KB
Raw

Contributing

Contributions to the OpenRailwayMap are appreciated!

For a number of specific types of contributions, there are detailed instructions below. In other cases, feel free to open an issue or pull request!

Use the instructions in the local development setup documentation to run the project locally. This can help to get a visual feedback on your changes.

I want to visualize a new train protection system on the map

Edit the file features/train_protection.yaml.

The file contains a list of train protection systems, each with a code, a legend and a color.

At the top of the file, add an entry for the legend, For example:

signals_railway_line:
  train_protections:
    # ...
    - { train_protection: 'new', legend: 'Description about this new train protection system', color: '#abc123' }
    # ...

In the body of the file, add a new entry at a certain place in the list. The rank should match the ordering of the entries. The value of train_protection should match the value in the legend entries. For example:

signals_railway_line:
  features:
    # ...

    - train_protection: new
      rank: 8
      tags:
        - { tag: 'railway:new', value: 'yes' }

    # ...

Open a pull request where you provide details about the new train protection system. Ensure the pull request contains references to documentation and places on the map where the train protection system exists.

I want to visualize a new railway signal

Railway signals are present on three layers. Find and edit the relevant file:

The file contains a list of train protection systems, each with a code, a legend and a color.

In the body of the file, add a new entry for the new railway signal. The signals are grouped by country. Every signal has a description, a set of tags and an icon. The icon can optionally have a match caluse to match tag values to render the feature differently based on the matched tag value.

For example, to match railway signals with tags railway:signal:shunting=AT-V2:verschubhalttafel and railway:signal:shunting:form=sign with icon de/ra10:

signals_railway_signals:
  features:
    # ...
    
    - description: Verschubhalttafel
      country: AT
      icon: { default: 'at/verschubhalttafel' }
      tags:
        - { tag: 'railway:signal:shunting', value: 'AT-V2:verschubhalttafel' }
        - { tag: 'railway:signal:shunting:form', value: 'sign' }

    # ...

A more complicated example where the different forms of features with tags railway:signal:main=AT-V2:hauptsignal and railway:signal:main:form=semaphore are rendered with different icons, based on the value of the railway:signal:main:states tag. Each of the cases will be matched as a regular expression against the tag value. These variants of the icon will also be shown in the legend, described by the description of each of the cases:

signals_railway_signals:
  features:
    # ...

    - description: Hauptsignal (semaphore)
      country: AT
      icon:
        match: 'railway:signal:main:states'
        cases:
          - regex: '^(.*;)?AT-V2:frei_mit_(4|2)0(;.*)?$'
            value: 'at/hp2-semaphore'
            description: '20/40 km/h'
          - regex: '^(.*;)?AT-V2:frei(;.*)?$'
            value: 'at/hp1-semaphore'
            description: 'clear'
        default: 'de/hp0-semaphore'
      tags:
        - { tag: 'railway:signal:main', value: 'AT-V2:hauptsignal' }
        - { tag: 'railway:signal:main:form', value: 'semaphore' }

    # ...

A final example for speed signals which display an icon depending on the matched speed value. The value property contains {} as part of the icon, which is replaced automatically with the matched tag value. In particular an example must be given, which is used in the legend:

speed_railway_signals:
  features:
    # ...

    - description: Geschwindigkeitsvoranzeiger (sign)
      country: AT
      icon:
        match: 'railway:signal:speed_limit_distant:speed'
        cases:
          - regex: '^(1[02]|[1-9])0$'
            value: 'at/geschwindigkeitsvoranzeiger-{}-sign'
            example: 'at/geschwindigkeitsvoranzeiger-80-sign'
        default: 'at/geschwindigkeitsvoranzeiger-empty-sign'
      tags:
        - { tag: 'railway:signal:speed_limit_distant', value: 'AT-V2:geschwindigkeitsvoranzeiger' }
        - { tag: 'railway:signal:speed_limit_distant:form', value: 'sign' }
    
    # ...

If the railway signal uses tags that are not in the list at the top of the file, ensure the tag is added there. For example:

signals_railway_signals:
  tags:
    # ...
    - 'railway:signal:combined:form'
    # ...

Next, ensure the icon exists in the symbols directory. The icon must be an SVG file, minified and of the correct dimensions (most icons are between 10 and 24 pixels wide / high).

Open a pull request where you provide details about the new railway signals. Ensure the pull request contains references to documentation and places on the map where these signals exist.

I want to visualize a new track gauge on the map

To be documented...

I want to improve the user interface

The HTML, Javascript and CSS of the user interface are located in the proxy directory.

Open a pull request where you provide details about the new train protection system. Make sure the pull request contains screenshots showing the user visible changes.

I want to provide translations for a new language

At this moment the user interface and legend are solely available in English. This might change in the future.