## 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.