Skip to main content

Massif style release

styles/massif is Python that writes MapLibre styles; everything a user downloads is generated from it. Users' side: Massif. How the style itself is written: styles/massif/README.md.

What is where​

PathWhat
styles/massif/*.py, layers/, palette.pythe generator
styles/massif/sprite-src/, sprite/the icon SVGs and the sheet made from them (committed)
styles/massif/<variant>.jsonthe MapLibre variants (generated, committed)
styles/massif/examples/the extension examples (osm, custom)
styles/massif/release/release.py (every flavour, npm, GitHub), site.py (the website's copy), screenshots.mjs, the npm README
styles/massif/demo/a page loading the MapLibre styles from the website, npm, a local release or the repo
styles/massif/LICENSEMIT-0: use it for anything, no notice required
carto/, dist/, family.jsongenerated, gitignored
tools/style-cli/the converter (mapbox2css) and compiler (css2xml)
tools/style-sprite/the sprite sheet (build.mjs) and the icon font's iconotype project (iconotype-project.mjs)
tools/style-preview/the style dev page (style preview)
styles/massif/compat.jsonthe oldest SDK these styles need
.github/workflows/release-styles.ymlCI build of every flavour; the published release

Building, from a clean checkout​

# the tools
(cd tools/style-cli && npm ci && npm run build)
(cd tools/style-sprite && npm ci)
(cd styles/massif/release && npm ci && npx playwright install chromium) # screenshots only
# the style compiler as wasm, for the compiled flavours: from a style-tools-v* release, or
(cd libs-massif/cartocss/util && emcmake cmake -B build-wasm -DCMAKE_BUILD_TYPE=MinSizeRel \
&& emmake make -C build-wasm massif-style && cp build-wasm/massif-style.{mjs,wasm} ../../../tools/style-cli/wasm/)

cd styles/massif
node ../../tools/style-sprite/build.mjs sprite-src sprite sprite # after an SVG change
node ../../tools/style-sprite/iconotype-project.mjs sprite-src/poi sprite-src/MassifIcons.iconotype.json \
--badge 10.5,10.5,27,27 # after a POI SVG change
python3 build.py # the MapLibre variants
python3 build.py --convert # and the SDK project into carto/, for the style preview

The flavours​

python3 release/release.py <version> [--only FLAVOUR]... [--screenshots] writes dist/: one folder and one massif-<flavour>-<version>.zip per flavour, dist/npm/ (the npm package), and with --screenshots one JPEG per variant.

  • maplibre — the committed variants, with the sources that have no public host (bathymap, contours, routes, satellite) swapped for empty placeholders of the same name. MapLibre refuses a style whose layer names a missing source, so the layers stay and the source is empty GeoJSON — or, for the raster, one transparent data: tile at z0: a raster source with no URL throws, and a raster layer reading GeoJSON stops the whole map drawing. sprite is made absolute, the website's v<version>/ folder by default (--base-url to change it): MapLibre resolves a relative sprite against the page, not the style, and draws nothing at all when the sprite fails. Minified; metadata["massif:version"] and ["massif:placeholder-sources"] added.
  • cartocss — build.convert() into the flavour folder, as --convert does into carto/.
  • cartocss-iconfont — the same conversion with --icon-font MassifIcons --icon-font-map <map> --icon-font-size 27 --fonts. The font is iconotype's (@iconotype/cli build) from the committed project sprite-src/MassifIcons.iconotype.json, which tools/style-sprite/iconotype-project.mjs writes from sprite-src/poi/: each badge SVG loses its plate (the first <circle>), its glyph box (--badge 10.5,10.5,27,27 of the 48 px badge) becomes the em, and iconotype's own fixer (init) makes the paths font-ready. Every name is mapped as each sprite the sheet bakes from it (restaurant, restaurant-poi, restaurant-mono). 27 is that box's height, so icon-size scales a glyph exactly as it scaled the sprite; the converter still measures the sheet's disc once for the plate the SDK draws under the glyph. A codepoint is a contract: FNV-1a of the name into U+E000–U+F8FF, the next free slot on a collision, and the existing project's codes kept first, so adding or removing an icon moves no other, and an app's own font built from another folder lands each name on Massif's character. An icon whose SVG is removed stays in the project, unselected, holding its code. The flavour ships the project and the script in iconfont/ (your own POI icons); the compiled one does not.
  • *-compiled — massif-style css2xml of every <name>.json of the folder, beside its icons/, fonts/ and legend.json. The XML keeps the parameters live ([param::variant]).

Checking a build​

  • gl-style-validate (@maplibre/maplibre-gl-style-spec) over dist/maplibre/*.json — CI runs it. It is what caught road_osm_low's ["config", …] reaching MapLibre paint: MapLibre has no config expression and the whole style failed to load. build.maplibre_style folds every config to the variant's default (lib.fold_config), keeping it only in massif:* metadata.
  • build.convert fails on any when() in the CartoCSS (per-feature, blocks rule pruning); the compiled flavours are the real compiler's output, so a CartoCSS that does not compile fails.
  • Look at it: run the style preview server, then
    • /styles/massif/demo/?from=dist — the MapLibre flavour of dist/, variant by variant; its SDK links open the style preview with the build's CartoCSS and icon-font flavours in the compare pane (?compare=/styles/massif/dist/cartocss-iconfont);
    • ?from=npm&version=<v> — the same for a published package, through unpkg;
    • ?from=site / site-v — the website's copy, once deployed.

Releasing from a machine​

To try the npm package before an official release — publish a prerelease under the next dist-tag, which npm install @massif-maps/styles does not pick up:

npm login # once; an account with publish rights on @massif-maps
cd styles/massif
python3 release/release.py 1.0.0-rc.1 --screenshots --npm next --dry-run # everything but the upload
python3 release/release.py 1.0.0-rc.1 --screenshots --npm next # publish the prerelease
python3 release/release.py 1.0.0-rc.1 --screenshots --npm next --github # and a GitHub prerelease

Then demo/?from=npm&version=1.0.0-rc.1 draws it from unpkg. --github makes the massif-styles-v<version> release with every zip (gh, logged in; a version with - is marked a prerelease), and the website picks it up on its next deploy. A prerelease's MapLibre JSON names the website's v<version>/ sprite, which exists only once the site has deployed that release: until then load it with the demo's sprite beside the JSON.

An official release from a machine is the same with --npm latest --github; prefer CI, which adds npm provenance.

Releasing from CI​

release-styles.yml:

  1. On a pull request touching styles/massif, tools/style-sprite or the converter: builds the wasm, every flavour and the screenshots, validates, uploads it all as an artefact. Nothing is published.
  2. Actions → Release → Run workflow with styles set to patch, minor, major, auto or a version, and publish on (Cutting a release, which also releases the SDK or the style tools in the same run). It calls release-styles.yml with the version plan worked out, and:
    • npm @massif-maps/styles@<version> (dist/npm, provenance, trusted publishing — no token);
    • GitHub release massif-styles-v<version> with every zip and massif-screenshots-<version>.zip, its notes the commits touching the styles since the last final massif-styles-v* (which commits);
    • docs.yml dispatched, since a release made with GITHUB_TOKEN triggers no workflow.

Versions are the style's own semver, never the SDK's: a change that moves what a variant draws is a minor, a renamed or removed parameter or variant a major. auto suggests from the commit titles; the run summary shows what it picked, and an explicit bump overrides it.

The SDK a release needs​

compat.json holds minSdk, the oldest SDK the styles work with. Raise it in the PR that makes a style use something newer (a new massif:sdk-* key, a converter flag such as --live-light). release.py writes it to the npm package.json (massif.minSdk), to every MapLibre style (metadata["massif:min-sdk"]), to the release notes and to versions.json on the website.

  • A number above the latest SDK release needs that SDK in the same run: plan fails otherwise.
  • "next" means "the SDK released together with these styles", for a PR that cannot know the number. plan resolves it to the SDK version of the run and fails when the run has none; the release then commits the number back to compat.json.

The website​

docs.yml runs styles/massif/release/site.py website/static/styles/massif: every non-draft massif-styles-v* release's MapLibre zip and screenshots unpacked under v<version>/, the newest also copied to the root (so …/styles/massif/streets.json is the latest), and versions.json. With no release yet it builds the root from the checkout.

The doc page's live map and screenshot grid (website/src/components/MassifStyleMap.js) read those paths, load the sprite from the site's own copy, and draw hybrid over EOX's Sentinel-2 cloudless 2016 mosaic (CC BY 4.0, credited in the map), as the screenshots do.