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.