From 4c195b7f2f4b60a8c1749596fd5eabe830726161 Mon Sep 17 00:00:00 2001 From: Michael Reichert Date: Sat, 25 Nov 2023 19:20:16 +0100 Subject: [PATCH 1/4] add a guide for (new) contributors --- CONTRIBUTING.md | 63 +++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 63 insertions(+) create mode 100644 CONTRIBUTING.md diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md new file mode 100644 index 00000000..583697d2 --- /dev/null +++ b/CONTRIBUTING.md @@ -0,0 +1,63 @@ +# Contributing to the CartoCSS map styles of OpenRailwayMap + +In this document, we provide a few tips if you want to contribute to the OpenRailwayMap CartoCSS map styles by creating pull requests. + +## Code formatting + +We use two spaces for indentation in our MapCSS and YAML files. + +## Test your code + +We like pull requests with example renderings. We will still make our own test renderings +but your test renderings help you to find bugs. You can use the provided Docker setup. + +If you provide test renderings or not, we appreciate recommendations for locations where to +make our test renderings. + +## New signalling systems + +Each country (sometimes each company) has their own signalling system. We welcome +other systems than those already supported by the style. New signals must be documented +on the OSM wiki and be actively used. + +## Map key + +The map key still makes use of the +[old MapCSS styles](https://github.com/OpenRailwayMap/OpenRailwayMap/tree/master/styles) +in the main repository. The `.mapcss` files are the style, the `.json` files +are the definition of the map key. + +## Icons + +All icons must be SVG files because we do not want to leave the users of the +style the freedom to render map images in any resolution they want. If someone +wants to print out OpenRailwayMap, they will benefit from a sharp icons. + +Please mind the following recommendations when you add new icons: + +* Country specific icons should be saved in `symbols//`. + If your country has different signals for different railway networks (e.g. + heavy rail and trams), it will be a good idea to create a subdirectory within + the country's directory. See Germany as an example. +* File names should match either the signal names, their abbreviations or their + English names. +* Keep in mind that the icons will be pretty small. Don't draw to detailed graphics. +* Icons should not have any padding. +* Signals (including boards) should not have a pole (except corner cases like poles + being a signal). +* SVG filters are not supported by Mapnik. +* Text should be inserted as paths. +* Please have a look at the XML code of your SVG files. We do not want XML code + full of metadata from your drawing software. +* We do not remove unnecessary whitespace from our SVG files. + +## Icons for speed signals + +Icons for speed signals should be provided in all existing variants if the speed signal +displays a number. If the signal shows a 5 for 50 kph, we want to render the icon with a 5, +not 9. Do not worry if you do not know all variants of that icon. Just add some variants, +the other ones can be add in the future. + +## Other remarks + +Please do not mix pure formatting changes with other changes. Diffs are read by humans. ;-) From ab4682580b8745d2bf52a91bb4b2f554917d8c74 Mon Sep 17 00:00:00 2001 From: Michael Reichert Date: Sat, 25 Nov 2023 22:01:31 +0100 Subject: [PATCH 2/4] improve wording --- CONTRIBUTING.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 583697d2..4e4b5748 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -20,9 +20,10 @@ Each country (sometimes each company) has their own signalling system. We welcom other systems than those already supported by the style. New signals must be documented on the OSM wiki and be actively used. -## Map key +## Legend -The map key still makes use of the +The legend at the OpenRailwayMap website explains users what the colors and +symbols on the map mean. It still makes use of the [old MapCSS styles](https://github.com/OpenRailwayMap/OpenRailwayMap/tree/master/styles) in the main repository. The `.mapcss` files are the style, the `.json` files are the definition of the map key. From 4f571ae1d5a5c98166f501087afb7bc2dd12789c Mon Sep 17 00:00:00 2001 From: Michael Reichert Date: Mon, 26 Feb 2024 17:13:15 +0100 Subject: [PATCH 3/4] Add more information about documentation of tagging, fix typo --- CONTRIBUTING.md | 7 +++++-- 1 file changed, 5 insertions(+), 2 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 4e4b5748..35e0b9da 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -18,7 +18,10 @@ make our test renderings. Each country (sometimes each company) has their own signalling system. We welcome other systems than those already supported by the style. New signals must be documented -on the OSM wiki and be actively used. +on the OSM wiki and be actively used. The wiki page should be linked from +[OpenRailwayMap/Tagging/Signal](https://wiki.openstreetmap.org/wiki/OpenRailwayMap/Tagging/Signal) +and follow the established naming conventions (usually `OpenRailwayMap/Tagging_in_`). +An English translation of the documentation is recommended but not a requirement. ## Legend @@ -57,7 +60,7 @@ Please mind the following recommendations when you add new icons: Icons for speed signals should be provided in all existing variants if the speed signal displays a number. If the signal shows a 5 for 50 kph, we want to render the icon with a 5, not 9. Do not worry if you do not know all variants of that icon. Just add some variants, -the other ones can be add in the future. +the other ones can be added in the future. ## Other remarks From 14066d0a39e5c21a86944d10c7ab4b336d5984f7 Mon Sep 17 00:00:00 2001 From: Michael Reichert Date: Mon, 26 Feb 2024 17:17:49 +0100 Subject: [PATCH 4/4] Add remarks about deployment Answers question in https://github.com/OpenRailwayMap/OpenRailwayMap-CartoCSS/pull/117#issuecomment-1826433666 --- CONTRIBUTING.md | 13 +++++++++++++ 1 file changed, 13 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 35e0b9da..98e25316 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -65,3 +65,16 @@ the other ones can be added in the future. ## Other remarks Please do not mix pure formatting changes with other changes. Diffs are read by humans. ;-) + +# Deployment new map styles + +Deployment is managed with Ansible in the +[server-admin](https://github.com/OpenRailwayMap/server-admin) repository. You +can find the currently deployed Git commit ID of the map style repository +there. You do not have to update this, it will be done by the administrators of +the server. + +Please mind that rerendering of existing map tiles has to be started +manually and can take a couple of days because serving tiles quickly is more +important than updating existing tiles. Use the context menu of the +[debug map](https://tiles.openrailwaymap.org/) to check when a tile was rendered.