Improve map style deployment process

[danrademacher]

Until this week, the process of deploying updates to our map styles into the Rails application has been tedious and manual.

@Rub21 wrote a script to make it less so: https://github.com/OpenHistoricalMap/ohm-deploy/blob/main/images/web/update_map_styles.py

This is a huge improvement, but there's one more part of the process:

The stylesheets reference spritesheets ~and glyphs~ that live on the map-styles repo in these lines:

• https://github.com/OpenHistoricalMap/map-styles/blob/staging/ohm_timeslider_tegola/tegola-ohm.json#L28-L29
• https://github.com/OpenHistoricalMap/map-styles/blob/staging/rail/rail.json#L26-L27
• https://github.com/OpenHistoricalMap/map-styles/blob/staging/japanese_scroll/ohm-japanese-scroll-map.json#L15-L16
• https://github.com/OpenHistoricalMap/map-styles/blob/staging/woodblock/woodblock.json#L15-L16

For the main OHM style, we had an issue long ago where we were editing the spritesheet to test style updates, and that was breaking the live production map. As a stopgap we made this script that simply copies the style json and spritesheets into _production versions and then we reference those in the tegola style: https://github.com/OpenHistoricalMap/map-styles/blob/staging/ohm_timeslider_tegola/make_production_version.py

To build on the improved deployment method Ruben has developed, I propose the following changes:

• [x] Rename ohm_timeslider_tegola to main.json in the map-styles repo and the relevant files on ohm-website. This will make it more obvious what the file is for.
• [x] Script the copy of spritesheets for each style into ohm-website so we're not live-linking to anything on map-styles Github Pages site.
• [x] Replace the references to those in the deployed ohm-website JSON stylesheets
• [x] Remove documentation at https://github.com/OpenHistoricalMap/map-styles/blob/staging/ohm_timeslider_tegola/README.md
• [ ] Document a method to test the style deploy script locally in the ohm-website local dev environment, so we can actually debug the latest styles there.
• [x] Clean up ohm-style.* JS files in the ohm-website repo to remove unneeded files and disused Javascript. May need updates to other JS files or HTML templates that call JS files?
• [x] Clean up map-styles repo to remove extra _production files and other cruft
• [x] Update the README at https://github.com/OpenHistoricalMap/map-styles/blob/staging/README.md with documentation of how the map style changes get deployed.

UPDATED: We rarely chang efonts, so we could leave the fonts as is in map-styles repo and just copy over the spritesheets.

[danrademacher]

Changes to map-styles are in a PR ready for review by @vknoppkewetzel and @tsinn. But before we merge that we have to remove the dependency on the spritesheet served out of map-styles or we will break the map on the live site.

[danrademacher]

Changes on the website code ended up being very minor -- keep the base style ERB since it still loads Maplibre RTL plugin (see https://github.com/OpenHistoricalMap/ohm-website/pull/247)

So I think what's left is these steps:

1. Update the deploy script to also copy over the spritesheets.
2. Deploy that once to remove live dependencies on spritesheets from map-styles repo.
3. Then merge https://github.com/OpenHistoricalMap/map-styles/pull/29
4. Update the deploy script to target main/main.json instead of ohm_timeslider_tegola/ohm_timeslider_tegola_production.json and associated spritesheets.
5. Deploy that
6. Update the documentation in the map-style repo for how all this works.

[Rub21]

@danrademacher could you check the progress is here https://github.com/OpenHistoricalMap/ohm-deploy/pull/327, it is ready to go to production.

[danrademacher]

Ok, just confirmed that all spritesheets are coming from staging.openhisotircalmap.org on staging:

hmm. now we have merge conflicts on the map-styles between this WIP PR https://github.com/OpenHistoricalMap/map-styles/pull/29 and the latest map styles. So I'll need to resolve those and merge to get latest map style code into main branch before we deploy this to production.

[danrademacher]

@Rub21 I merged the changes in map-styles and this new PR should be ready to merge to staging: https://github.com/OpenHistoricalMap/ohm-deploy/pull/328/

If that works, then this is good for production

[Rub21]

@danrademacher seems the Styles has broken in overpass-turbo:

[danrademacher]

Ah drat. That's the one place we were pulling the stylehseet live! Once we deploy the new method to production, we could modify Overpass Turbo to point at the production website mapstyle JSON, which is better

that's a change to this line https://github.com/OpenHistoricalMap/overpass-turbo/blob/master/js/configs.js#L6

[Rub21]

nice, so this is ready to go production!

[Rub21]

The changes are already in production : https://www.openhistoricalmap.org/

[1ec5]

That's the one place we were pulling the stylehseet live!

Oh, there’s more…

• OpenHistoricalMap/map-styles@116d5d1f2ce443a3c7cabba528ddf7288c7d2279 — fixes icons in the Railway style, needs deployment
• OpenHistoricalMap/map-styles@9bc752a1c73e4605c0ba0fbacd6a259aeac2d9d5
• OpenHistoricalMap/leaflet-ohm-timeslider-v2#12 — fixes icons in the demo styles
• OpenHistoricalMap/mbgltimeslider-leaflet-control#24
• OpenHistoricalMap/ohm-embed-1yr@448427f34463d30f0aafe7d45a835eb92ebf582b — fixes embed.openhistoricalmap.org
• OpenStreetMap Wiki:
  • Documentation for direct embeds on websites
  • Documentation for Overpass Ultra settings
  • Example Overpass Ultra query
  • Announcement to Web developers
  • Maps gadget that embeds OHM maps on various pages, such as the main OHM portal
• Request to make the same change on the AARoads Wiki, where OHM maps are embedded in some articles

There’s no telling how many people followed the documentation to hard-code the old URL. But I’m glad we’ve simplified the URL to something that makes more sense.

[danrademacher]

Oy, OK, hard lesson learned here. As a stop gap, I could make a copy of the main map style and spritesheet under the old name. Then roll this out more thoughtfully.

[1ec5]

I’m not sure there’s a great solution. Copying the file would erase the file’s edit history, so it would be more difficult to track down regressions in the future. I wonder if GitHub Pages supports any kind of rewrite rule or symbolic link that would let us keep a redirect around. Anyways, “main” is a good enough name; no need to overthink it right now.

[Rub21]

Can we close this ticket?

[danrademacher]

We still have one open task here:

• [ ] Document a method to test the style deploy script locally in the ohm-website local dev environment, so we can actually debug the latest styles there.

I don't quite remember right now if we ever had a method to locally pull in the latest map styles for testing. I think that's still copy-paste by hand. Actually, I'm make a new ticket for just that bit.