Docs: Notes on adding an icon library

[tordans]

Based on #207 I was wondering what is needed to add a new icon library.

This doc can be used as a way for us to agree on a process and also as a reminder which parts to modify when we add a library.

There are a few takeaways for me here…

• do we agree that adding an icon library is not a breaking change … because we expect consumers to have fallbacks in place? (I think this is fine…)
• we should look into bundling the icons ourselves so other apps don't have to do it all again… (should we create an issue for this?)
• we should check that the new library is easy to implement for the main apps. For iD this means we need a npm package; for SC it needs a flat folder structure,…

[matkoniecz]

we should look into bundling the icons ourselves so other apps don't have to do it all again… (should we create an issue for this?)

maybe we also should ping data consumers what their preference is, maybe they would not benefit from it and prefer to keep it inside their stack?

[matkoniecz]

maybe we should contact data consumers and let them know about it? Or is mentioning in release notes sufficient?

[tyrasd]

Yeah, please include this as an explicit step

Suggested change

	5. **Each editor / consumer** that renders preset icons: extend its own resolution or bundling (see below).
	5. Contact the maintainers of **each editor / consumer** that renders preset icons: to inform them that they need to include the new icon set in their own icon resolution or bundling (see example instructions below).

[matkoniecz]

should it be documented here or in iD and linked here?

[k-yle]

do we agree that adding an icon library is not a breaking change … because we expect consumers to have fallbacks in place? (I think this is fine…)

i think it's definitely a breaking change if icons suddenly stop working for some presets.

 

imo we should not add any more vendor-specific code. if we need a new icon source, i think we should switch to an icon aggregator like iconify or pinhead¹ or icones.js. This is significantly easier for data consumers, who can pull every icon from a standardised JSON file instead of hardcoded logic for every provider.
And it allows us to add many new icon providers, without a breaking change.

we should look into bundling the icons ourselves so other apps don't have to do it all again

we should check that the new library is easy to implement for the main apps [...]

an icon aggregator would solve both these issues too

Footnotes

1. pinhead only has CC-0 icons so it's probably too limited ↩

[matkoniecz]

pinhead only has CC-0 icons so it's probably too limited

if we would add one with more restrictive licenses then ideally we would also build necessary attribution (or at least remind data consumers to do so)

[tyrasd]

do we agree that adding an icon library is not a breaking change … because we expect consumers to have fallbacks in place? (I think this is fine…)

IMHO, that is fine. We should have a convention in place to not immediately start "mass"-replacing icons from existing icons over to the newly added icon set, in order to give data consumers time to implement the new source in their toolchains. But for new presets or presets which only had very poor generic icons, it would be fine to immediately start using the new icon set.

Should we mention this somewhere? 🤔

[tyrasd]

imo we should not add any more vendor-specific code. if we need a new icon source, i think we should switch to an icon aggregator like iconify or pinhead or icones.js. This is significantly easier for data consumers, who can pull every icon from a standardised JSON file instead of hardcoded logic for every provider.

Maybe I'm overlooking something… but data consumers are already free to use an icon aggregator to ingest the icons, in case it makes sense for their toolchain. If they do so, they don't have to do anything whenever we add a new icon set for the id-tagging-schema (as long as it is included in the respective aggregator), otherwise they do have to adjust their vendor-specific code. So, this is mostly just an implementation detail for the respective data consumer, not something we need to document here, maybe with the exception that we would "promise" to stick to only icon sets that are available through a particular aggregator, so consumers can rely on it somewhat. The downside of this would be of course that, on the other hand, it would also make us less flexible in what specific icon sets that we can add: e.g. osmic (#207) is AFAICS not available through any of the mentioned aggregators.

And it allows us to add many new icon providers, without a breaking change.

I don't think we should strive to add many new icon providers: The benefit of the current system is that the icons are reasonably consistent within each other: we do allow a couple icon sets that are specific to cartography (maki, temaki and röntgen that each cover slightly different aspects of map related iconography, maybe a few more in the future), and for everything else we allow fontawesome which does have a large amount of generic icons. Adding more general-purpose icon sets would only lead to relatively few additionally available icons, but instead to lots of icons where there are duplicates available. This would potentially only lead to less and less consistency of icons between each other (e.g. in terms of level of detail, style, etc.). Another benefit is that contributors don't have to scan through a dozen or so icon sets when looking for a suitable icon for a new preset.

---

So, what I'm trying to say is: we should continue to only allow to use a curated selection of icon sets for the tagging-schema. We can add more after individual consultation/discussion, and then proceed using e.g. the proposed workflow from this PR.

[tyrasd]

we should look into bundling the icons ourselves

Maybe… I'm not sure. I think in practice it varies quite a lot how specifically different software consumes the tagging schema in general, depending on the programming language, deployed device type, etc. To start, some will use the npm package (either directly, or through a CDN), some might rely on github releases or even main branch on github. Then, some applications might want to access icons individually, some might want to bundle them into sprites. It would definitely be quite a bit of effort to build/maintain something that works for everyone. What we potentially could do with relatively little effort is to transfer the preprocessing iD is doing over to the tagging-schema build scripts. But I'm not sure anyone outside of iD/rapid would realistically use it exactly in that way.¹

The benefits would be:

• the icons would always be exactly as we want them to be (in case the icons change from one version of an icon set to the next)
• it would be easier for data consumers if we add new icon sets
• data consumers don't need to pay attention to update icon sets whenever they receive an update

Footnotes

1. An alternative thing we could technically do is to directly inline the icons on the individual presets as a data-uri using the existing imageURL property. But that would potentially lead to quite a bit of duplicate data for all icons that are used on more than one preset. ↩

[matkoniecz]

Maybe I'm overlooking something… but data consumers are already free to use an icon aggregator to ingest the icons, in case it makes sense for their toolchain.

so they can basically lookup machine-readable source info and use that to match aggregated icons? But of we add one more source then they would likely add more custom logic anyway

[matkoniecz]

imo we should not add any more vendor-specific code. if we need a new icon source, i think we should switch to an icon aggregator like iconify or pinhead1 or icones.js.

I am quite confused. Why adding pinhead-specific code would not be adding one more vendor-specific code?

(I want to add pinhead - it has https://pinhead.ink/#person_sitting_on_lifeguard_stand_above_water which would enable fixing openstreetmap/id-tagging-schema#1571)

[matkoniecz]

Suggested change

	This document describes what has to happen when the tagging schema adopts icons from a **new family** (a new string prefix). The latest addition in practice was **`roentgen-`** ([Röntgen](https://github.com/enzet/map-machine#r%C3%B6ntgen-icon-set) icons; see also [`ICONS.md`](../ICONS.md)). It complements the contributor-facing overview there.
	This document describes what has to happen when the tagging schema adopts icons from a **new family** (a new string prefix). See [`ICONS.md`](../ICONS.md) for already added ones. It complements the contributor-facing overview there.

we really should not add parts doomed to get stale

[matkoniecz]

Suggested change

	## Is this a breaking change to the JSON schema?
	**No**, we do not consider a new icon prefix a breaking schema change.
	In [`schemas/preset.json`](../schemas/preset.json), `icon` is a free-form string, so values such as `roentgen-ford` need no schema update.
	Apps and libraries should fall back when an icon is unknown or missing (e.g. generic glyph or text only); with that in place, new prefixes should not break integrations; the experience is simply weaker until explicit support exists.
	## Is this a breaking change to the JSON schema?
	**Yes**, as some of already existing presets may start using icons from the new set.
	In [`schemas/preset.json`](../schemas/preset.json), `icon` is a free-form string, so values such as `roentgen-ford` need no schema update.
	Apps and libraries should fall back when an icon is unknown or missing (e.g. generic glyph or text only); with that in place, new prefixes should not break integrations entirely; the experience is simply weaker until explicit support exists.

I disagree whether it counts or should count as a breaking change

[matkoniecz]

2. **id-tagging-schema**: use "icon": "prefix-name"in presets, categories, or fieldicons.

that surely should be the last step? or at least after

4. id-tagging-schema: bump the schema-builder devDependency and rebuild.

[matkoniecz]

we should here link SC docs if they exist, not make backup of them