Skip to content

document header tagging conventions #618

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
bashbaug merged 1 commit into from
Aug 12, 2026
Merged

document header tagging conventions #618

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
16 changes: 16 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -200,6 +200,22 @@ python3 bin/makeExtinstHeaders.py
Right now there is only a single version of both the GLSL and OpenCL
headers. So we don't yet have a problematic example to resolve.

* *How and when is this repo tagged?*

Because there are many users of the SPIR-V headers, this repo is tagged using
several tagging conventions:

1. For each Vulkan SDK release, the repo is tagged with the Vulkan SDK version
to record the SPIR-V headers used by that version of the Vulkan SDK. For
example, the tag `vulkan-sdk-1.X.YYY.Z` indicates the SPIR-V headers that
were included in the Vulkan SDK version `1.X.YYY.Z`.
2. For other uses, the repo is tagged using a [CalVer](https://calver.org/)
date-based scheme on an as-needed basis. For example, the tag `vYYYY.0M.R`
indicates release `R` of the SPIR-V headers in the zero-padded month `0M`
of the full year `YYYY`.

@oddhack oddhack Aug 2, 2026

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW Khronos long ago agreed to use ISO(*) 8601 (2026-08-01) date format in general. Tags are an outlier case since the date is imbedded and there's some history associated with them.

(*) It is nice for standards groups to use standards themselves. Personally I wish people would stop using local and often nonexistent or temporally incorrect timezone codes when sending out meeting announcements in favor of UTC, but I digress.

@bashbaug bashbaug Aug 3, 2026

Copy link
Copy Markdown
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I think this proposal is mostly consistent with ISO 8601. The main difference is . vs. - as the separator. If we want to treat the tag as a traditional version, I think . makes sense, but I'm flexible.

AFAICT ISO 8601 also mandates a four-digit year YYYY and a zero-padded (and hence, unconditionally two-digit) month 0M, so this is all consistent.

I'm open to including the date in our tags also, but this could get awkward if we ever end up needing to tag twice on the same day. In this case, is the first tag e.g. v2026.08.03 and then the second tag is v2026.08.03.1? Or do we always include the "release", so the first tag on a day would be v2026.08.03.0? Both of these options would work, but they seem verbose to me.

We could also go coarser, and just include the year and the release, so initially v2026.0, followed by v2026.1, etc. It looks like SPIRV-Tools releases follow this convention, FWIW, though if this repo adopts a similar convention it could also generate confusion if users expect the SPIRV-Tools tags to match the SPIRV-Headers tags.

3. Other, older tagging conventions previously existed in this repo, but are
no longer actively used.

## License
<a name="license"></a>
```
Expand Down
Loading