# OpenStreetMap Carto contribution guidelines

## Reporting issues

The OSM Carto project is now very mature and many issue reports turn out to be
duplicates of existing issues. Before reporting a potential issue, please do a
quick search of the repository to check for related issues - including closed ones.
If you do find a matching issue, please review the previous discussion and ensure
that any additional comments are constructive. Unhelpful comments e.g. "Why hasn't
this been fixed yet?" are not constructive and will be marked as off-topic.

As OpenStreetMap data is always changing, rendering bug reports should **always**
contain a cropped screenshot of the problem, and a link to the area. Don't assume
that we will see exactly what you see. If a particular OSM object is an issue,
the issue should contain the tagging of the object.

## Rendering samples to illustrate issues

Samples from the map you include in an issue/comment to show a problem or support
an argument in the discussion should always be provided as rendered.  Please avoid
posting samples re-scaled to a different resolution after rendering.  You may add
arrows or other markers if such are helpful to identify a specific location you
want to point out, but you should not otherwise modify the map.

In particular, you should never try to modify a map screenshot to disguise the
geographic location the map sample is from.  This is almost never going to be
successful and - if it is - it will render your sample pretty useless to the style
developers because they are not going to be able to reproduce the problem.   If
you don't want to disclose the location where you have found an issue you either
need to find a different location where the problem occurs as well or try to
reproduce the issue in a style development environment using abstract test data.

## Workflow for making contributions

Contributions to the development of OSM Carto are very welcome; the project is
entirely reliant on external contributions. Significant changes, including 
additional rendering, should always be discussed through the issue mechanism
first; this will avoid potential frustration at the review stage.

We operate the "Fork & Pull" model explained at
https://help.github.com/articles/about-pull-requests/

You should fork the project into your own repo, create a topic branch
there and then make one or more pull requests back to the upstream repository.
Your pull requests will then be reviewed and discussed.

Pull requests that change the cartography should contain a few images selected
to show the changes. The easiest way to make these is by taking screenshots and
cropping them, then pasting them into the issue. Avoid adding an overwhelming
number of screenshots. The images are not intended to replace reviewing changes
in Kosmtik or TileMill, but to provide an overview.

### Previews

Some changes benefit from a review over a wider area and many zooms, where static
images might not be sufficient and a demo layer is necessary. The OSM Carto project
currently does not have the infrastructure for testing style changes in a live
rendering environment, but you can ask if there are contributors willing and able
to do more comprehensive testing.

## Easy pickings

Some [easy issues](https://github.com/openstreetmap-carto/openstreetmap-carto/labels/good%20first%20issue) have been selected
that are particularly suitable for new contributors to get familiar with the project's code base and the contribution process.

## Editing layers

OpenStreetMap Carto uses a YAML file for defining layers.
[Kosmtik](https://github.com/kosmtik/kosmtik) and CartoCSS can directly load the project from
the YAML file with `node index.js serve path/to/openstreetmap-carto/project.mml`

## CartoCSS style guidelines

* Always specify zoom levels as either >= or < . Don't use = or =< or >.
* Open curly braces on the same line, and close on an empty line.
* One space before and after = etc
* Two space indents. No tabs.
* space after : but not before
* Dashes, not underscores, in layer names
* Avoid restating defaults, e.g. don't add `point-allow-overlap = false`.
* Avoid repeating the layer name for layers with multiple attachments, i.e., prefer

```mss
#layer {
  ::outline {
    line-width: 6;
    line-color: black;
  }
  ::inline {
    line-width: 2;
    line-color: white;
  }
}
```
instead of

```mss
#layer::outline {
    line-width: 6;
    line-color: black;
}
#layer::inline {
    line-width: 2;
    line-color: white;
}
```
* Order the selectors in a style-sheet in rough order of importance (i.e.,
  `highway=primary`, then `highway=secondary`) and beyond that, add layers that
  are rendered later (i.e., higher) lower in the file.
* For features where the symbolizer attributes change on different zoom levels,
  the main definition should be for the lowest zoom level. Also, avoid nesting
  zoom-based overrides. For example:

```mss
#layer[feature = 'foo'][zoom >= 13] {
  line-width: 6;
  line-color: black;
  [zoom >= 15] {
    line-width: 7;
  }
  [zoom >= 17] {
    line-width: 10;
  }
}
```
instead of
```mss
#layer[feature = 'foo'][zoom >= 13] {
  line-width: 10;
  line-color: black;
  [zoom < 18] {
    line-width: 7;
    [zoom < 16] {
      line-width: 6;
    }
  }
}
```
* Use the PostgreSQL quoting syntax for attributes (columns) and string-values of selectors.
  Use no quotes or double quotes for attributes (columns) and single quotes for string-values.
  For Example:

```mss
#layer[entrance = 'yes'] {
  marker-width: 6.0;
}
#layer["generator:source" = 'wind'] {
  marker-width: 8.0;
}
```
instead of
```mss
#layer[entrance = "yes"] {
  marker-width: 6.0;
}
#layer['generator:source' = 'wind'] {
  marker-width: 8.0;
}
```

## SQL style guidelines
Because SQL within YAML will not generally be syntax highlighted, indentation and caps are particularly important.

* SQL keywords in caps, as in PostgreSQL documentation
* Two space indents. No tabs.
* Start with `(SELECT` and start the columns on the next line.
* Two indents for columns, to bring them to the same indent level as later clause contents
* Add indentation after `SELECT`s until the end of the sub-select.
* Add indentation for contents of `FROM`, `WHERE`, `ORDER BY` and other clauses
* Put content with WHERE, etc if it's short
* Add indentation if necessary for complex function calls, WHERE parentheses, and CASE statements
* One space before and after = etc
* Name SQL subqueries after the layer name (but use underscores)
* When extracting tags from hstore, use `tags->'foo'`, not `tags -> 'foo'`, and only add parentheses if needed for order of operations
* Hstore queries tested for NULL should be enclosed in parentheses, e.g. `(tags->'foo') IS NULL`.
* To check if a tag is in the tags hstore, use `tags @> 'foo=>bar'`, relying on automatic conversion from `text` to `hstore`.

## Map icon guidelines

* All new icons must be in SVG format.  The SVG must be saved as standards compliant SVG without any proprietary tags. In Inkscape software, you will need to "Save As..." and choose the format Optimized SVG (preferable) or Plain SVG.
* Icons must use SVG fills only, not SVG strokes or any feature Mapnik does not support.
* Use no color for the icon's fill if the icon is monochromatic. This allows the color to be set in the MSS.
* Use a common canvas size, which is usually 14x14 px.
* Convert shapes and other components to paths and merge them into a compound path.
* Draw a simple siloutte of the subject with an "on the shelf" perspective.
* Align vectors to the pixel grid otherwise detail will be lost when rendered to a bitmap.
* Make a clean design, so reduced complexity where possible.

### External icon design resources
The project's goals and design philsophy are different from other projects, but some external resources with general information about icon design are:

* [Maki Icons Design Guidelines](https://labs.mapbox.com/maki-icons/guidelines/)
* [GNOME Icon Design Guildelines](https://developer.gnome.org/hig/guidelines/ui-icons.html)

## Typography

This style uses the font "Noto" for a world-wide coverage of scripts. The font
size should be ≥ 10 px for legibility once rastered to screen resolution.

### Multi-line labels

Additional to text-size we have to set text-wrap-width and text-line-spacing.
For both, the absolute value is quite meaningless; it should rather be
interpreted relative to the font size (em) that has been set in “text-size”:
```mss
text-size: 10;
text-wrap-width: 30; // 3.0 em
text-line-spacing: -1.5; // -0.15 em
```
- The text-size is 10, so we have: 1 em = 10
- The text-wrap-width should be 3.0 em, so we have: 3.0 * 10 = 30
- The text-line-spacing should be -0.15 em, so we have: -0.15 * 10 = -1.5

If text-size increases on higher zoom levels the other parameters also have
to be adjusted to guarantee the same line wrap and same relative line spacing:
```mss
text-size: 12;
text-wrap-width: 36; // 3.0 em
text-line-spacing: -1.8; // -0.15 em
```

Usually, with higher zoom levels we increase the line length
(text-wrap-width measured in em!).

Following an old typography convention, we use narrow
line spacing for short lines and wider line spacing for longer lines.
```mss
text-size: 15;
text-wrap-width: 75; // 5.0 em
text-line-spacing: -0.75; // -0.05 em
```
Noto’s line spacing is rather large to allow also tall scripts like Myanmar
to be rendered without collisions. But the line spacing is too large for
cartographic usage; therefore we reduce the line spacing. Currently, the
line spacing ranges from -0.15 em to -0.05 em. (Even at -0.15 em, collisions
are seldom and even then the text stays legible).

## Syntax highlighting

Most of the style development happens within CartoCSS MSS and MML files. Syntax highlighting can make editing more pleasant.

Editors based on KDE Frameworks (Kate, KWrite, KDevelop…) provide syntax highlighting for CartoCSS MSS out-of-the-box, and starting with KF 5.100 also for CartoCSS MML, including SQL highlighting within the YAML structure.

Also, Yohan Boniface [has developed](https://github.com/yohanboniface/carto-atom) highlighting for CartoCSS MSS for editors that use the TextMate Language Grammar for syntax highlighting: Atom (install package “language-carto”), Visual Studio Code, Jetbrains…
