codegen/vulkan/vulkan-docs-next/READMEVK.adoc

// Copyright 2017-2023 The Khronos Group Inc.
// SPDX-License-Identifier: CC-BY-4.0

ifdef::env-github[]
:note-caption: :information_source:
endif::[]

= Vulkan^(R)^ API Documentation Project

The link:https://github.com/KhronosGroup/Vulkan-Docs[Vulkan-Docs]
repository (or the equivalent internal Khronos tracking repository)
contains sources for the formal documentation of the Vulkan
API. This includes:

[options="compact"]
  * The Vulkan API Specification
  * Specification of API extensions
  * API reference ("`man`") pages
  * The XML API Registry (also mirrored at
    link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
  * Vulkan header files (also mirrored at
    link:https://github.com/KhronosGroup/Vulkan-Headers[Vulkan-Headers])
  * Related tools and scripts.

The authoritative public repository is located at
link:https://github.com/KhronosGroup/Vulkan-Docs/[Vulkan-Docs].
It hosts a public Issue tracker, and outside developers can file proposed
changes (Pull Requests) against the Specification, subject to approval by
Khronos.

If in doubt where to submit your Issue, consult the
link:https://github.com/KhronosGroup/Vulkan-Web-Registry/blob/main/Vulkan-Projects.adoc[Vulkan-Projects] list on the link:https://github.com/KhronosGroup/Vulkan-Web-Registry[Vulkan-Web-Registry]
repository.

The Vulkan-Docs repository also includes the sources for the Vulkan SC
specification in order to simplify the long-term maintenance of the Vulkan SC
specification. These are not considered normative. The formal sources for
Vulkan SC can be found as detailed in link:READMESC.adoc[READMESC.adoc]

== External Contributions

Khronos welcomes feedback in GitHub Issues, and proposed changes in GitHub
Pull Requests (PRs), but will not necessarily accept all such changes.

Please keep your issues and pull requests focused on solving a single
problem. Broader feedback that tries to solve multiple problems, or touches
many parts of the Specification at once, is difficult for the Vulkan Working
Group to review in a timely fashion.


== Branch Structure

The current Specification is maintained in the default branch (currently
`main`) of the repository.
From this branch it is possible to generate Specifications for any published
version of Vulkan (1.3, 1.2, 1.1, and 1.0), and incorporating any desired set of
extensions.
Each published update is tagged in the form `1.3.*release*` where *release*
is a constantly incrementing release number and `1.3` is the latest
published version of the API.
The last public spec update prior to Vulkan 1.3 is tagged `v1.2.???`.

The last state of the default branch in Khronos' internal GitLab server,
before 1.3 content was merged into it, is tagged `1.2-archive` (this tag is
not in GitHub).