C.9. Documenting Extensions

Extensions are documented as modifications to the Vulkan specification.
These modifications will be on Git branches that are named with the
following syntax: <major.minor core spec version>-<extension_name>

For example, the VK_KHR_surface extension will be documented relative
to version 1.0 of the Vulkan specification. As such, the branch name will
be: 1.0-VK_KHR_surface

If the extension modifies an existing section of the Vulkan
specification, those modifications are made in-place. Since the changes are
on a branch, the core-only specification can be easily produced. A
specification with an extension is created by merging in the extension’s
branch contents.

Extensions should be merged according to their registered extension number.
If two extensions both modify the same portion of the specification, the
higher-numbered extension should take care to deal with any conflicts.

The WSI extensions were used to help pioneer what should be done for
extensions. This includes the following:

All extensions should add to the appendix of the Vulkan
specification. This should be modeled after what was done for the
VK_KHR_surface extension, which contains some high-level information
about the extension (as well as code examples, and revision history) in
the appendices/vk_khr_surface.txt file.

Each extension’s appendix file is included by adding an include
statement to the vkspec.txt file. Since most extensions will all put
their include line at the same place in this file, they should add
this statement on the master branch, even though the file won’t actually
exist on the master branch. This will avoid merge conflicts when
multiple extensions' branches are merged in order to create the “full”
branch specification.

If there are any other places where 2 or more extensions will extend the
Vulkan specification, it is best to put that content in a file, and
use an include statement to put that content into the spec. Again,
this include line should be put on the master branch in order to
avoid merge conflicts.

If an extension is more of an addition to the Vulkan specification,
the extension should add a chapter to the Vulkan specification.