A suggested contribution roadmap

[chrisdebian]

Hi, Hugo.

I came across golfTiles through the OSM community and wanted to say it looks like a really valuable project. The idea of golf-centric vector tiles from OSM data, built on tilemaker and served as PMtiles, fills a genuine gap; and the pipeline you have working already is impressive for such an early stage.

I have spent some time reading through the README, todo.md, process.lua, run_all.sh, and the golftiles.org site, and I have put together a suggested contribution roadmap. I want to be clear that this is offered in the spirit of helping, not criticism; please feel free to take, leave, or reshape any of it as you see fit.

The roadmap is organised into five phases:

Phase 0 — Code health and immediate technical debt

• process.lua TODOs: There are a number of inline TODO comments in process.lua that could each become a dedicated GitHub issue, keeping the code free of stale annotations. The most actionable is the trio of -- TODO log to some file to process comments in set_AttributeInteger_and_log() — completing this would produce a bad_tags.csv on each run, directly enabling the todo.md item about uploading a fixable dataset for the OSM community.
• run_all.sh: The TODO at line 9 could become an issue. The script would also benefit from set -e and set -o pipefail to prevent silent failures mid-pipeline.
• golftiles.org: The GitHub link on the homepage appears to be broken (it resolves to golftiles.org/github.com/... rather than https://github.com/...). A basic MapLibre GL JS embed showing one of the existing sample PMtiles would make the project immediately tangible to new visitors.
• todo.md: Would it be worth converting the items in todo.md and the README's next-steps checklist into GitHub Issues, so contributors can pick things up without having to read across multiple files?

Phase 1 — Data quality pipeline

The tilemaker output already produces a large number of Invalid integer warnings from malformed OSM tags (e.g. hole_number=7 & 16, par=4/5, dist=332 yd). Two improvements here:

• Structured export: Complete the logging stub to write a bad_tags.csv per run (columns: osm_type, osm_id, key, value). This could seed a MapRoulette challenge or Overpass query for community-led OSM data cleanup.
• Graceful parsing: Harden the Lua to handle the most common real-world patterns — stripping unit suffixes from dist, extracting integers from X/Y or X & Y formats in hole_number and par, treating named hole variants (e.g. hole_number=Becton 1) as strings rather than attempted integers.

Phase 2 — Schema documentation

• A SCHEMA.md documenting the three layers (facilities, golf, other), their zoom ranges, all attributes, and the rationale for key decisions — following the shortbread-docs model already mentioned in the README.
• A configuration doc explaining the osmium and tilemaker parameters and their memory/performance trade-offs.
• Wiki contributions covering penalty area tagging (water_hazard, lateral_water_hazard, surface variants) and the architect tag — both noted as open items in todo.md.
• Implementing name:<CODE> multi-language subtag support, currently noted as a TODO in general_attributes().

Phase 3 — Testing and CI

• Lua unit tests (e.g. using busted) covering the integer-parsing logic, with test cases drawn from the known-bad tag values in the UK extract output.
• GitHub Actions CI running the full pipeline on a small extract, validating that the output PMtiles file exists and contains the expected layers. The README already lists this as a next step.

Phase 4 — route=golf relation support

This is the highest-impact item: reading hole order from route=golf relations and assigning values to golf_hole= tags, enabling correct multi-course facilities and the animated hole viewer. The current while true do loop in way_function() has an inline comment noting it needs reworking to handle multiple relations. Would it be worth resolving the design question (namespace prefix vs. separate geometry per route) with input from FairwayMapper and the OSM golf tagging community before implementation begins?

Phase 5 — Community and visibility

• A CONTRIBUTING.md covering environment setup, how to run a test tile generation, and coding conventions.
• Coordinating with FairwayMapper on the route=golf schema, given the shared goals.
• A follow-up OSM diary post or forum thread sharing the bad_tags output and Overpass queries, once the export is working.

---

I am happy to contribute to any of the above, particularly the data quality work and documentation, where my OSM background is most relevant. Would any of this be useful? And are there areas you would rather keep focused on for now?

Thanks,

Chris

[HuggeK]

Hi @chrisdebian, I didn´t see your post, hadn´t turned on all notification on the repo itself but many things you mentioned i dsicovered. I could move the TODOs inline into issues but my focus has been to get something up and running and verify that i can get all the tools working, now the grunt work with the style can begin and some refinements to the schema, seing that it is one kind of geometry per layer I have learned in maplibre gl js. I have also succefully been able to run Maputnik locally due to the CORS issues. Wrote more on that in the readme.md.

I should have been more clear that this is a pre-pre release and not even a 0.1 yet - I want to have the basics of a style in place before pushing a tag/release. I mandated merge requests(pullrequests in github-land) now too to hopefully clean up the commit history. The inline TODOs are things that I´m going to fix before that release. and the opionon about it being cumbersome to read through multiple files I don´t especially share. I think if i know where somehting should be placed and the language I am writing in supports comments, I will just write it out to be able to actually get back to what I was doing, then absolutely one could create issues for lenghtier discussions - but it is hard to reference lines when the code changes so much. For things thta people can do if they want to help I put some preliminary under: https://github.com/HuggeK/golfTiles#contributions , mainly the javascript/typescript golf course animations which we need a more stable schema to access the data on the vector attributes themselves(no need to query a slow overpass instance when you have already fetched the data)

In regard to Phase 1 - Data quality pipeline - I have asked around on the discord and It seems like some format that maproulette and/or the format the TODO plugin is expecting in JOSM is a good idea to not reinvent the wheel - we are first and foremost in this project about consuming the data and the quailty works in such a way that it discard data if it is not in the right types according to the wiki before needing parsing in client side javscript for endconsumers/apps. It is better to actually motivate editors to write good values (please usemeters as the wiki says if you have not annoted the data to explain to data consumers that it is yards you are using) instead of having to write so much custom lua code, just becuase the tilemaker approach is not the final goal. That would be to rewrite all process schema code in sql on a postgis database and a tileserver to be able to serve more frequent updates. See discussion on discord: https://discord.com/channels/413070382636072960/607265062322700308/1511826755235741696

In regards to Phase 2 - as I have writen in the TODO´s, it will be done but as I had a gut feeling that this approach of puting almost every golf features regardless of its geometry was wrong so more layers need to be added to be able to style it.

I cannot see any solution to solve the name: multi-language subtag support because we need to know the Key in advance.

In regards to phase 4 - I don´t follow what you think is blocker? A sanity check for order of holes is just a nice to have and not a must - our most important milestone is to produce good tiles - that we can style and then how we produce these are second, just becuase the rewrite for a postgis database in the future (but still trying to support a tilemaker configuration as before) every hole has a ref= already and the route=golf is new. Seperate geometry for route should only be for our exported tiles, nothing to do with the osm data and what I can see it is not favourable. Putting all the info on the golf=holes themselves I think is the only logical step in working with tiled vector features.

I have done extensive updates to the wiki in regards to golf tagging also in paralell with this development to hopefully get a good groundwork for a datamodel which can serve us well.

I hope I don´t come across as crossed, I am not - I should have made the repo private before I got a relative stable schema and then we can work togheter.

//Hugo

[HuggeK]

That said, it would be valuable if we could gather atleast 15 persons for a proper RFC vote on now golf features, see some of my proposals: https://wiki.openstreetmap.org/wiki/Tag:leisure%3Dgolf_course#Proposals%CB%90 jsut becuase the out of bounds one is really valuable for us but got downvoted last years becuase of people who do not play golf and think that a out of bounds marker line is the same as a bollard....

[HuggeK]

If you know how to setup GitHub Actions CI on some small extracts It would be great if we could get that to generate on each pull request - I have no previous experience in that.

[HuggeK]

Another thing I also would need help is how we configure osmium to not include stuff outside of the leisure=golf_course facility polygon but still be able to run tilemaker.

[chrisdebian]

Hi Hugo,

Thank you for the very detailed response — this is really helpful. The core message is clear: pre-pre-release, style and schema first, keep it pragmatic.

A few notes on what I am revising from the original proposal based on your feedback:

• Inline TODOs — totally understood; working notes are working notes. I will leave those completely alone.
• name:\u003cCODE\u003e multi-language — you are right, the key needs to be known in advance. Dropping it.
• route=golf hole animation — agreed this is premature without a stable schema. Parking it.
• Lua unit tests — CI coverage of the full pipeline addresses the most important risk; unit tests can follow later if needed.

Here is a revised roadmap reordered around your two explicit asks:

Revised contribution roadmap

Phase 0 — Immediate code health

• 0-001 Fix the broken GitHub link on golftiles.org (currently resolves to golftiles.org/github.com/... rather than https://github.com/...)
• 0-002 Add set -e and set -o pipefail to run_all.sh so that a silent failure mid-pipeline does not produce a partial output without any error

Phase 1 — CI: test fixture and pipeline validation

• 1-001 Commit a small .osm fixture alongside the existing data/ placeholder — a realistic 2–3-hole golf course with a mix of valid and intentionally malformed tags (e.g. hole_number=7 & 16, par=4/5). This sidesteps the gitignore restriction on real extracts and makes CI fully reproducible.
• 1-002 Add a GitHub Actions workflow (.github/workflows/tile-gen.yml) that converts the fixture to .pbf with osmium export, runs run_all.sh, and asserts the output .pmtiles is present and non-empty. Runs on every pull request.

Phase 2 — osmium extract: boundary fix

Your todo.md already flags this ("TODO maybe clip the pbf file again to get rid of these vast areas which stretch outside of the course boundary"). The current --strategy=smart with -S types=multipolygon,route pulls in complete ways even when they extend beyond the golf course polygon.

The fix is two steps:

• 2-001 Replace --strategy=smart with --strategy=complete_ways in the extract step — this removes the route-type expansion that causes the spill
• 2-002 Add a second osmium tags-filter pass immediately after, discarding any non-golf ways dragged in by the complete_ways expansion

Phase 3 — Schema stabilisation

• 3-001 Once the style MVP is in place, I am happy to help document and test the layer splits (one geometry type per layer). You already have the right mental model from the maplibre GL JS experience.

Phase 4 — Data quality output

• 4-001 Complete the bad_tags.csv logging stub in set_AttributeInteger_and_log() — writing osm_type, osm_id, key, value per row on each pipeline run
• 4-002 Format the output as a JOSM TODO plugin file or MapRoulette challenge input — as you noted from the Discord discussion, motivating editors to fix values at source is the right approach

Phase 5 — Documentation

Once the schema is stable:

• 5-001 SCHEMA.md documenting the final layer set, attributes, and zoom ranges
• 5-002 PIPELINE.md covering the osmium and tilemaker parameters and their trade-offs
• 5-003 CONTRIBUTING.md covering environment setup and how to run a test tile generation locally

---

I am happy to start with Phase 0 and Phase 1 now — the code health fixes and CI workflow are the most self-contained contributions and do not depend on the schema stabilising. I will raise individual issues for each item before opening any pull request.

Thanks again for the detailed feedback and for the extensive wiki work on golf tagging.

Chris

[HuggeK]

Chris? Your now second Phase 1 is written about some gitignore, what? What is an OSM fixture? What do you mean? ”1-001” is also not a placeholder data, that is where the user puts the extracts (.pbf) files for the script to pull in the data.

”Phase 0” as you call it is already done, see main.

2-001 does not change the output when I tested with the data, tilemaker is not happy about about using simple strategy on non complete relations - that needs to be researched and tested.

2-002 Is not possible because we do not know what tags we want before we process it with tilemaker. (expect those two relations)

5-001 - in regards to make a .md file for the schema, I have now brought in the next steps as issues as you requested - and as deoxygenate before I think the best way would be to do as Shortbread does it with some Hugo run to GitHub Pages.

[HuggeK]

#31 now it is an issue to take care of the cmpute that has been spent on to figure out what values is malformed.

[chrisdebian]

Hi Hugo — thanks for the detailed follow-up. Looking at your questions, I think it is clear you have a specific technical direction in mind (osmium polygon filtering, CI on PBF extracts) and my roadmap suggestions were getting ahead of where the project actually is. I am going to step back from the structured contribution plan; it is creating more noise than value at this stage. I wish golfTiles well — the schema and style work you are doing sounds genuinely promising. I will follow along from a distance.