Repo reorganization

[birkskyum]

As mentioned in #206 , the lines between maplibre-gl-js and maplibre-style-spec seem a bit arbitrary, and it mixes up the versioning of the style spec with both the versioning of the GL JS implementation and the style spec utilities implementation

I suggest the current style spec repo is split into 3 areas

• The .json files that are the single source of truth for the style spec / expression tests.
• The style spec docs
• The style spec utilities (validation / format)

The .json files would be imported by Native and GL JS, where expression test implementations etc. are to be found and executed, and then GL JS would be imported into and used in the style spec utilities library and to build the style spec docs.

In practice, this means:

• All the .ts files in this repo that GL JS import, and the files they depend on, should be moved back to GL JS. In cases where classes currently exist in both repos, we can even deduplicate.
• All the expression tests can be moved to the style spec repo, and be deleted from GL JS.
• If the approach of a submodule is taken, the docs / style spec utilities would also be added to the repos where the .json files are used if this is kept as one repo. This can be avoided either through creating additional repos for docs and/or style spec utilities, or by uploading the .json files as github release artifacts and downloading them e.g. as .tar files if it's preferred.

[birkskyum]

@louwers , @HarelM , here's a discussion thread. The open questions here are:

• Is it's alright that the style spec validation effectively would be lagging behind the implementation in GL JS
• Is a submodule or a github artifact preferred, which ties a bit into another questions which is that if an artifact is preferred, would it be confusing to publish the style spec validation from the same repo

[HarelM]

Thanks for opening this thread!!
I'm not sure I fully get the big picture.
Can you outline how the repositories will look like after everything is done, i.e the desired state?
If it's a single file artifact might be enough, for multiple files downloading a zip and then extracting isn't a great solution. But I need to better understand the big picture before we get into this specific detail.

[birkskyum]

This could be done with 3 repositories.

Style Spec repository.
/ reference / v8.json
/ test / expression / *.json
CHANGELOG.md (only for style spec, which still is at v8.x)
README.md

Docs repo
Everything form the current /docs folder in style-spec repo
maplibre-gl, or if necessary maplibre/maplibre-gl-style-spec, installed in package.json

NPM module repo (maplibre/maplibre-gl-style-spec)
Everything from the current style-spec repo, with the /docs and v8.json removed
maplibre-gl installed in package.json
CHANGELOG.md (only for maplibre/maplibre-gl-style-spec package, which is what the current changelog is used for - it's at v19.x)

[birkskyum]

Alternatively, since these repos are quite small, we can also keep them in one repo like now and subtree the whole thing if it's not a problem. In that case, three sections above become three folders, like in the PR i made initially

[HarelM]

For me, it makes sense to split it into two:
Jsons files and docs, as the docs use the spec json file for the docs generation, but hopefully doesn't need anything else, and the npm package (or move the code back into maplibre-gl?) Although having a repo for the npm package makes a lot of sense to me, as it's very clear what the repo is for, this repo doesn't have to have github pages if this is the concern here.
Otherwise, if we keep it in a single repo I would like to have package for style validations in other languages so that we have some symmetry.
IDK... just a thought...

[birkskyum]

the docs use the spec json file for the docs generation, but hopefully doesn't need anything else

Unfortunately this isn't the case at the moment, because there are some typescript files with a lot of meta information of the json document used for parsing it to the docs. I don't know if these files are key to maplibre-gl, or the style spec utils, or if they are only in use for the docs, and I hope this reorg can help shed some light on it.

[HarelM]

Bottom line, 3 folders are OK from my point of view as it will not change this repo dramatically.
We can always decide afterwards how to restructure it going forward...