Skip to content

Commit 90dc07b

Browse files
committed
Add contributing chapter
Refs #24
1 parent ba22409 commit 90dc07b

File tree

2 files changed

+40
-0
lines changed

2 files changed

+40
-0
lines changed

CONTRIBUTING.adoc

Lines changed: 36 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,36 @@
1+
// Copyright 2023 The Khronos Group, Inc.
2+
// SPDX-License-Identifier: CC-BY-4.0
3+
4+
= Khronos Vulkan^®^ Tutorial Contributing
5+
6+
Contributions to this repository are welcome and anyone is free to contribute. But please read the following guidelines on how to contribute.
7+
8+
== License
9+
10+
The contents of this repository are licensed as https://creativecommons.org/licenses/by-sa/4.0/[CC BY-SA 4.0], unless stated otherwise.
11+
By contributing to this repository, you agree to license your contributions to the public under that same license.
12+
13+
== Ways to Contribute
14+
15+
* Small fixes like typos, grammar errors, or other minor changes
16+
** Feel free to create a PR, it'll usually get merged quickly
17+
* Adding new content or making larger changes
18+
** We are mostly driving forward development within an internal Khronos Group, any larger external contribution should be coordinated beforehand. So if you plan on doing a larger change, please open a new issue to inform us up-front and we'll get back to you and coordinate this
19+
20+
== Technical background
21+
22+
Before contributing, make sure you read through these to understand how the tutorial works and why it's structured the way it is.
23+
24+
=== Antora site generator
25+
26+
The tutorial is meant to be rendered as part of the link:https://github.com/KhronosGroup/Vulkan-Site[Vulkan Documentation Project site]. That project makes use of link:https://antora.org/[Antora], a multi-repository documentation site generator.
27+
28+
As such the tutorial is not meant to work or be viewed outside of that documentation site. That means things that may seem broken in e.g. github's preview (like missing images) are fine due to how Antora works.
29+
30+
Any change or fix needs to consider this and make sure that it follows Antora's requirements. This is relevant for the content as well as the structure (see link:https://docs.antora.org/antora/latest/standard-directories/[Antora standard directories]). So if you e.g. want to add screenshots, they need to go into that folder structure.
31+
32+
=== Markup format
33+
34+
The content's of the tutorial are written in Asciidoc (adoc file extension). New content or changes to existing content need comply with this format. If you are new to Asciidoc, the link:https://docs.antora.org/antora/latest/asciidoc/asciidoc/[Antora's Asciidoc primer] is a good starting point.
35+
36+
Similar to other markdown languages, most development environments support live preview for Asciidoc. For Visual Studio Code, link:https://marketplace.visualstudio.com/items?itemName=asciidoctor.asciidoctor-vscode[this extension] is recommended. It's advised to set the `asciidoc.preview.useEditorStyle` extension setting to `false` to get a preview look similar to the Antora site and also enable the extension's `asciidoc.antora.enableAntoraSupport` option.

README.adoc

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -15,3 +15,7 @@ By contributing to this repository, you agree to license your contributions to t
1515

1616
The code listings in the `code` directory are licensed as https://creativecommons.org/publicdomain/zero/1.0/[CC0 1.0 Universal].
1717
By contributing to that directory, you agree to license your contributions to the public under that same public domain-like license.
18+
19+
== Contributing
20+
21+
Contributions are welcome, details on how to contribute and the technical requirements that have to be met can be found in link:CONTRIBUTING.adoc[this document].

0 commit comments

Comments
 (0)