Maintaining specifications for 3D Tiles 1.0, 1.1, and beyond

[javagl]

There are efforts for the standardizing 3D Tiles version 1.1. This version will be based on what is currently referred to as "3D Tiles Next", which currently is a set of (draft) extensions for 3D Tiles 1.0, that offer the core functionality that is supposed to be standardized as version 1.1.

We have to find a way to sensibly maintain and organize different versions in this repository. The approaches here could roughly be categorized as follows:

• Always maintaining the "latest" state, and using Git tags for versioning
• Creating different subdirectories for the different versions

3D Tiles 1.0, 'Next', and 1.1 should coexist, should easily be accessible, and may have to be maintained independently (for smaller bugfixes). And some of the current repository contents will be (largely) independent of the underlying version (but that might change if there is a version 2.0 at some point). So I think that trying to find a directory-based versioning mechanism makes more sense in our case.

Current state

Right now, the directory structure of the repository is

\                             Main README

\specification                Specification README for 1.0
\specification\schema         Schema for 1.0
\specification\TileFormats    Tile formats of 1.0     

\specification\Metadata       Specification for Metadata  
\specification\Styling        Styling functionality

\extensions\3DTILES_...       Extensions for 1.0 - these "ARE" "3D Tiles Next"!

\reference-card               Reference card for 1.0  

\next                         Main README for 3D Tiles Next
\next\reference-card          Reference card for 3D Tiles Next

^{(Omitted some additional files, like figures directories that refer to the respective README etc.)}

Directory layout options

The options for organizing different versions in such a directory structure differ in the detail. This basically refers to the level of "granularity" on which the version numbers are inserted, affecting the question of which part a certain version applies to.

Very roughly speaking, one could start "pragmatically", with a layout like this:

\specification\1.0                Specification README for 1.0
\specification\1.0\schema         Schema for 1.0
\specification\1.0\TileFormats    Tile formats of 1.0     

\specification\1.1                Specification README for 1.1
\specification\1.1\schema         Schema for 1.1

With the obvious caveats:

• The reference-card subfolders require versioning. But are not part of the "specification" in the narrow sense.
• The extensions should be separate of the "core" specification. But they strictly belong to one version. And right now, all extensions belong to 3D Tiles 1.0, and are what is referred to as "3D Tiles Next"
• The next folder belongs to 1.0, but ... is not part of the core specififcation. This is the odd one out. In some sense, the extensions could/shuld be a subfolder of next...

One could move the version information "up" in the hierarchy, leading to something like this:

\                                 Main README

\1.0                              Entry point for 1.0    
\1.0\specification                Specification README for 1.0
\1.0\specification\schema         Schema for 1.0
\1.0\specification\TileFormats    Tile formats of 1.0     
\1.0\reference-card               Reference card for 1.0  

\1.0\extensions\3DTILES_...       Extensions for 1.0 - these "ARE" "3D Tiles Next"!
\1.0\next                         Main README for 3D Tiles Next (this only belongs to 1.0!)
\1.0\next\reference-card          Reference card for 3D Tiles Next (this only belongs to 1.0!)


\1.1                              Entry point for 1.1
\1.1\specification                Specification README for 1.1
\1.1\specification\schema         Schema for 1.1
\1.1\reference-card               Reference card for 1.1  
\1.1\extensions\                  (Extensions for 1.1 will go here...)

\specification\Metadata           Specification for Metadata  
\specification\Styling            Styling functionality

Note: There currently is no anticipated versioning mechanism for \specification\Metadata or \specification\Styling. They are somewhat independent of the 3D Tiles version. But they might require some versioning mechanism as well in the future. (Will this versioning be "aligned" to the 3D Tiles version? May there be a "Styling 2.0" for "3D Tiles 2.0"? Or could "3D Tiles 2.0" use "Styling 1.1"? Should they be just put into the 1.0 directory, and the 1.1 directory could just point to these, saying that ~"nothing changed here"?)

[lilleyse]

Thanks for putting this together @javagl. Lots to think about.

Some comments on the separate directories approach...

• I prefer subdirectories in the specification folder e.g. \specification\1.0\schema \specification\2.0\schema
• extensions - this folder should have subdirectories too, I think. The 1.1 folder would be empty to start.
• next - this directory may not exist after 1.1 is complete. The revision history would need to move elsewhere. The material from the 3D Tiles Next reference card could be added to the 1.0 reference card to create a new 1.1 reference card. There should be a separate reference card for each version.
• Metadata and Styling - this one's tough. I could even see them being different repos in the future...

I'm a bit worried about the scalability of the separate directories approach if we start to do more frequent revisions, say a minor release every half year or so (or even every year). The tagging approach will allow us to move faster if we realize there's things that need to be added post 1.1 but pre 2.0. If maintenance of older versions becomes a problem we could consider using branches instead of tags.

[javagl]

One point that could me mentioned here explicitly: There will probably be PDF files that represent "releases" - namely, the documents that will be THE standardized specification, verbatim, with strict versioning and release date. And even though they will likely be maintained in other places as well, in one form or another - like https://docs.opengeospatial.org/cs/18-053r2/18-053r2.html for 3D Tiles 1.0 - there should probably be a "releases" folder in the repo.

(This folder should then contain the documents that have been removed in https://github.com/CesiumGS/3d-tiles/pull/668 )

[javagl]

Some details that have been mentioned in this issue still have to be decided upon. I think that having a 1.1 release in the sense of GitHub releases ( https://github.com/CesiumGS/3d-tiles/releases ) could make sense, capturing the whole repository state at a given point in time. Beyond that, I could imagine that a releases subdirectory could make sense, which contains exactly and only the PDF files with the final, official releases.

Additionally, there now is A proposal for a 3D Tiles packaging format specification, raising the question of where this could be maintained, and how to manage the releases. The input for this specification also consists of a set of ADOC files. The output is a PDF file. But its versioning is unrelated to that of the 3D Tiles core specification. So I think that it could make sense to reflect this in the directory structure (roughly: to not maintain this in a subdirectory of the specification directory, but maybe in a sibling directory like packagingSpecification). But everybody can add further suggestions here.

[javagl]

The current approach is:

• There is only one specification directory that contains the latest state (i.e. 1.1 at the time of writing this). Older states can always be reproduced via tags, because each state is tagged (currently, there are 1.0 and 1.1 tags)

• There is a releases directory that contains the full, final OGC standard releases, as PDF files, for all versions

• The reference cards are offered as PDF files in the top-level directory. The sources (SVG files) are in the reference-cards/1.0 and 1.1 directory

  • The difference here compared to the main specification is justified by the fact that the reference card for 1.1 does not describe version 1.1 as a whole, but only the additions compared to 1.0. So maintaining the 1.0 and 1.1 in separate directories makes sense. Iff there ever is a single reference card that covers 1.0+1.1, then this can be changed.

• The solution for future specification elements (e.g. that of the 3D Tiles Packaging format) will have to be decided on a case-by-case basis

So there are some details that might come up again in the future, but can then be tracked in dedicated issues.