1 files changed, 111 insertions, 0 deletions
diff --git a/codegen/vulkan/README.adoc b/codegen/vulkan/README.adoc
new file mode 100644
index 00000000..6826917a
--- /dev/null
+++ b/codegen/vulkan/README.adoc
@@ -0,0 +1,111 @@
+// Copyright 2017-2021 The Khronos Group Inc.
+// SPDX-License-Identifier: CC-BY-4.0
+
+ifdef::env-github[]
+:note-caption: :information_source:
+endif::[]
+
+= Vulkan^(R)^ API Documentation Project
+
+This repository contains sources for the formal documentation of the Vulkan
+API. This includes:
+
+[options="compact"]
+ * The Vulkan API Specification
+ * Specification of Vulkan 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.
+
+
+== 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.2, 1.1, and 1.0), and incorporating any desired set of
+extensions.
+Each published update is tagged in the form `1.2.*release*` where *release*
+is a constantly incrementing release number and `1.2` is the latest
+published version of the API.
+The last public spec update prior to Vulkan 1.2 is tagged `v1.1.130`.
+
+The last state of the default branch in Khronos' internal gitlab server,
+before 1.2 content was merged into it, is tagged `1.1-archive` (this tag is
+not in github).
+
+
+== Directory Structure
+
+The directory structure is as follows:
+
+```
+README.adoc           This file
+BUILD.adoc            Documents how to build the specifications and reference pages
+CONTRIBUTING.adoc     Requirements for external contributions to the repository
+COPYING.adoc          Copyright and licensing information
+CODE_OF_CONDUCT.adoc  Code of Conduct
+LICENSE.adoc          Summary of licenses used by files in the repository
+ChangeLog.txt         Change log summary for each public spec update
+Makefile, make*       Makefile and helper build scripts (see BUILD.adoc)
+appendices/           Specification appendices
+chapters/             Specification chapters
+proposals/            Design documents for extensions
+config/               Asciidoctor configuration, CSS, and index generator
+images/               Images (figures, diagrams, icons)
+gen/out/              Default directory for the generated documents
+scripts/              Helper scripts used in specification, header, and reference page generation
+style/                Sources for "styleguide" (Vulkan Documentation and Extensions: Procedures and Conventions)
+xml/                  XML API Registry (vk.xml)
+registry.txt          Sources for documentation of the vk.xml format
+```
+
+
+== Building the Specification and Reference Pages
+
+The document sources are marked up in Asciidoctor format, and we use
+`asciidoctor` and related toolchain components to generate output documents.
+See link:BUILD.adoc[BUILD.adoc] for more information on installing the
+toolchain and building the Specification.
+
+
+== Generating Headers and Related Files
+
+See link:xml/README.adoc[xml/README.adoc].
+
+The header files (`include/vulkan/vulkan*.h`) and many parts of the
+specification and reference page documents are generated from descriptions
+in the XML API Registry (link:xml/vk.xml[`xml/vk.xml`]).
+The generated files are not checked into the repository.
+If you change `vk.xml`, you can regenerate the headers by going into
+`xml/` and running:
+
+    $ make clean install
+
+The other generated files are built as required via dependencies in
+the top-level `Makefile`.
+