Skip to content

Latest commit

 

History

History
93 lines (74 loc) · 3.46 KB

CONTRIBUTING.adoc

File metadata and controls

93 lines (74 loc) · 3.46 KB
Raw

Vulkan Guide Contributing

While open for contributions from all, there are a few contribution rules in place.

The main design goal for the Vulkan Guide is to be “lean” and prevent any duplication of information. When possible the Vulkan Guide should guide a user to another resource via a hyperlink.

Ways to Contribute

  • Fixing a typo, grammar error, or other minor change

    • Please feel free to make a PR and it will hopefully get merged in quickly.

  • Adding new content

    • If you think the guide needs another page, please raise an issue of what topic you feel is missing. This is not a requirement, but we hope to avoid people spending thier valuable time creating a PR for something that doesn’t quite belong in the guides.

    • If adding another link, clarification, or any other small blurb then a PR works. The addition of information needs to not be redundant and add meaningful value to the guide.

  • Feel the guide is not accurately portraying a topic

    • There are a lot of ways to use Vulkan and the guide is aimed to be as objective as possible. This doesn’t mean that the current information on the Vulkan Guide might be slightly incorrect. Please raise an issue what you feel is incorrect and a solution to how you would improve it.

Images

All images must be no wider than 1080px. This is to force any large images to be resized to a more reasonable size.

Markup

The Guide has been converted from Markdown to Asciidoc markup format. It is possible to view the individual chapters (pages) as before, starting with the repository root README.adoc, or to generate a single document containing each chapter using 'make guide.html' with the 'asciidoctor' command-line tool installed.

We have added experimental support for the Antora site generator under the antora/ directory. See https://github.com/KhronosGroup/Vulkan-Site for details and links to a site incorporating the Vulkan specification, proposals, and this guide.

When adding new chapters, or adding cross-references to existing chapters, it’s necessary to take these steps:

  1. Links to new chapters must be added at the appropriate place in README.adoc and the corresponding place in antora/modules/ROOT/nav.adoc, using the existing conventions of each file.

  2. For each chapter chapters/page.adoc which contains internal cross-references, add this boilerplate at the top of the document:

    ifndef::chapters[:chapters:]

    or, for chapters chapters/extensions/page.adoc, add this boilerplate:

    ifndef::chapters[:chapters: ../]

  3. When creating an internal cross-reference link to chapters/page.adoc, mark it up as follows:

    This is a xref:{chapters}page.adoc#anchor[cross-reference]

    If cross-referencing chapters/extensions/page.adoc, mark it up as follows:

    This is a xref:{chapters}/extensions/page.adoc#anchor[cross-reference]

  4. The anchor is arbitrary, but is not optional. While asciidoctor will generate anchor names automatically based on section titles, for link stability it is best to use an explicit anchor on the title of the target file:

    ifndef::chapters[:chapters:]

[[anchor]]
= Target Page

Together, these steps allow cross-references to resolve correctly whether viewing the Guide as a single document, or a set of related pages.