What changed from 2.0.0 to 2.0.1?
psilord opened this issue · 9 comments
Hello,
When looking at the specification page for glTF, I notice that a 2.0.1 came out. Great!
What changed from 2.0.0?
There doesn't appear to be any separate change document or section in the specification PDF about what changed from the previous version. In addition, there doesn't appear to be inline notes in the document about what changed either. Searching for "2.0.0" or "2.0.1" or "previous" doesn't lead to this information in the document.
How do I find this information out (especially in a way that doesn't entail running git log and reading commit entries or the commits themselves)?
Thank you!
I also suggest that each version of glTF have its own line in that specification page along with links to the document in pdf or html form. According to that page, the gltf 2.0.0 document is simply lost. Luckily, I have a copy, but if I didn't, I don't know where to get one.
The changes between 2.0.0 and 2.0.1 have only been editorial changes. So there have been no changes that affected the scope, functionality, constraints, or other aspects of the specification. The only changes have been typos, formatting, or details of images.
@lexaknyazev I'm surprised that we don't have Git tags for 2.0.0 and 2.0.1. I know that the releases do carry a commit hash, but ... there doesn't seem to be a list of "previous releases" (i.e. the PDF file for 2.0.0 can only be found indirectly, but apparently not in the Khronos registry).
So... there may not be an "overview" for the actual changes. The thing that comes closest to "The Truth" is probably comparing the states of the commit hashes for the (released) 2.0.0 and 2.0.1 versions:
Thank you for your response and comments!
Might I humbly suggest that when a new spec version is released, a permanent link be created in that spec page to the PDF and HTML, and maybe a new appendix added to the document explaining the changes (or at least what sections to compare) between the current and previous release? You've already identified that tags should be made and that's a great idea!
I had implemented the glTF 2.0.0 specification into a library for a game engine we're writing, but when the new spec came out and the other developers asked me to update the code...I had no idea even how to find concisely what changed so I can update the code! I submit this is a common path for how "customers" use these specifications and deal with their evolution. The recording of the changes should be sufficient that I can know in what parts of the specification I need to look in order to ensure I can update the library as required...or see that just some editorial changes happened and all is actually just fine. :)
I submit a strong opinion that "doing a git diff between two hashes" is NOT an appropriate method for someone to learn what the changes were and how to formally interpret their meaning and context.
I deeply appreciate the time and effort you've spent on designing this specification, writing it up, and maintaining it.
Thank you!
I agree that there should be some place where the previous version can be accessed more conveniently.
Technically, this would probably happen in https://github.com/KhronosGroup/glTF-Registry .
(An aside: That's also where you can access the previous version, e.g. via the glTF 2.0.0 commit in https://github.com/KhronosGroup/glTF-Registry/commits/main , which leads to the PDF at https://github.com/KhronosGroup/glTF-Registry/blob/24fd81ae013f12d43bac5a327c757cb07706d12b/specs/2.0/glTF-2.0.pdf )
I also agree that doing a diff between hashes is not a sensible way to compare the changes. But again, the changes between 2.0.0 and 2.0.1 have only been editorial. Of course, one could add a change log like
- Replaced the hyphen in SPIR-V with a non-breaking hyphen
- Removed spaces in
and / orand changed it toand/or - Added captions to images [...]
- Replaced the word "image" with "figure" in section [...]
- Added a comma in section [...]
- ...
But ... that wouldn't be useful, IMHO.
Regarding your library, specifically:
It should not be necessary to change any code for the update from 2.0.0 to 2.0.1. The version numbering is that of https://semver.org/ (as far as this is applicable to a specification). None of the changes between 2.0.0 and 2.0.1 should affect the meaning of the specification, and therefore, they should not affect the implementation.
Thank you for the link references!
I agree that the example level of detail for editorial changes you provide above is too detailed.
But if something was that specific for actual specification changes, then it might warrant that level of detail.
I think my questions and feedback have all been answered to my satisfaction.
Thank you very much!
I'll leave the closing of the ticket to you in case you wanted to do additional discussion or not.
In case it's helpful to know – the glTF 2.0 specification was released six years ago, in 2017. Since then, I believe the only changes to the core specification have been either editorial, or clarifications of ambiguities. All new functionality has been added in the form of extensions, instead, and I expect that will continue to be true unless/until there is a glTF 3.0.
If there will be a change in the specification that really affects the format (and that is not only editorial), then this will certainly be highlighted in a change log. Until now, there are no specific plans for this, and possible updates to the spec that are only editorial will be handled with 'patch' version updates (i.e. the next version would only be 2.0.2).
I assume that this issue can be closed, but feel free to reopen if there is further need for discussion.
It might be better to leave this open until the question about the availability of the 2.0.0 PDF release is resolved. This might be moved into an own issue in https://github.com/KhronosGroup/glTF-Registry , but maybe someone wants to chime in with further thoughts here.
Khronos does not maintain older patch releases of the specs. For example, the latest Vulkan 1.3 spec (currently 1.3.262, gets updated every few weeks) is always found at the same place:
- https://registry.khronos.org/vulkan/specs/1.3/pdf/vkspec.pdf (PDF)
- https://registry.khronos.org/vulkan/specs/1.3/html/vkspec.html (HTML)
The version of the glTF file format is 2.0 and all updates within the 2.0.x lifecycle are limited to formatting and clarifications. Should those clarifications be substantial (e.g., defining a previously undefined edge case), a changelog entry may be added.
Khronos may not officially maintain them. But when the registries are maintained on GitHub, then GitHub will implicitly maintain them. I think that one could at least consider to offer them officially, just to make it easier for people to access these PDF files in a form that is more convenient than looking through git commits. But ... that could be considered on a case-by-case basis. For glTF, it would be doable, given that there has been a single patch update in 5 years. The Vulkan spec, on the other hand, has version number 1.3.263, and having a list of 263 PDF files wouldn't make sooo much sense.
The core of this issue should be resolved. Offering patch versions directly in the registry is not considered for now. If it comes up again, it can be tracked in the glTF-Registry repo.