KhronosGroup / KhronosGroup/Vulkan-Loader

Please document JSON file format compatibility rules

Open
#248 5 comments 0 reactions 0 assignees View on GitHub

Nobody has claimed this yet.

enhancement
Dominant language
C
Stars
696
Forks
343
Avg merge
1d 1h
Merged PRs (30d)
17

Description

Thanks for documenting the JSON file format specification - it's a useful resource, and I'm now trying to add a similar (but simpler) spec to GLVND for the EGL ICDs.

https://github.com/KhronosGroup/Vulkan-Loader/blob/master/loader/LoaderAndLayerInterface.md#icd-manifest-file-format documents that the current file format is 1.0.0, but does not document what formats a consumer can assume to be compatible with the current format.

Similar code in GLVND says this:

The minor version number will be incremented if we ever add an optional
value to the JSON format that libEGL has to pay attention to. That is,
an older vendor library will still work, but a vendor library with a
newer format than this library understands should fail.

https://github.com/NVIDIA/libglvnd/blob/master/src/EGL/libeglvendor.c#L279

If the intention is to have the same versioning policy as GLVND/EGL, perhaps something like this would be appropriate:

Versions 1.0.x are required to be compatible with this specification, in the sense that a consumer that only implements file format version 1.0.0 will load all version 1.0.x JSON files successfully (a new micro version may add new fields but will not break compatibility with existing loaders). Newer major and minor versions might require loader changes.

(I'm not sure what the intended distinction is between major and minor versions, if an increment to the minor version is allowed to include incompatible changes.)

Contributor guide

Open the contributing guide

First steps

  1. Read the whole issue, then the project's contributing guide.
  2. Comment on the issue to say you are picking it up — it saves two people doing the same work.
  3. Fork the repository and make your change on a branch.
  4. Open a pull request that references the issue number.

Research direction

Start with loader/LoaderAndLayerInterface.md and its ICD manifest file format section, then compare the compatibility wording in GLVND's src/EGL/libeglvendor.c. Resolve or confirm the intended major, minor, and micro version rules, and document which JSON versions a 1.0.0 consumer must accept.

Written by the indexing model from the issue text.

Assessment

Domain
documentation
Issue type
Documentation
Difficulty
2/5
Estimated time
1-3 hours
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.