xref: /third_party/vk-gl-cts/external/vulkan-docs/src/proposals/template.adoc

// Copyright 2021-2024 The Khronos Group Inc.
//
// SPDX-License-Identifier: CC-BY-4.0

= Proposal Template
:toc: left
:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/
:sectnums:

.How to use this document
[NOTE]
====
This document outlines the expected flow of a proposal - text in the following sections is there as guidance for how to fill out each section.
When creating a new proposal, text inside these sections (including this note!) should be removed and replaced with actual proposal text.

Proposal documents are standalone and do not use the attributes and extensions associated with the specification - they should be independently buildable with Asciidoctor, which allows them to be previewed live on GitHub/GitLab.

When calling out existing API constructs or extensions, the `refpage` attribute should be used to link to the relevant Khronos reference page.
For example - "...used to extend link:{refpage}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo]..."
====

A short summary of this proposal should be written here.

== Problem Statement

This section should detail the problem that is being addressed as succinctly as possible.
Usually this comes in three parts:

 . Setting the scene
 . Bulleted list of problems
 . (Optional) Describe peripheral issues
  a. I.e. things this may enable solutions for, but does not directly address.

Writing this section is a good opportunity to make sure you are not overreaching by trying to address too many problems at once.

== Solution Space

This section should briefly describe the options that have been considered (this is a good time to reconsider those options too!).

Start with a bulleted list of the options, usually no more than a paragraph on each option and what the pros/cons of each are, then some sort of brief reason for picking the proposal you are about to make in section 3.

== Proposal

This section should be the most detailed – it should go into enough detail on specific points of the proposal that readers can understand it, but without being overly verbose.
Typically, this section will be split into subsections describing different areas of the proposal.

This should only describe the minimum viable proposal; all those extra things that you could put on top that do not necessarily fix the initial problem should move to section 5 (further functionality).
They may make it into the final proposal, but it is important to give others the opportunity to evaluate these independently.

== Examples

Where relevant, add one or more examples of how this proposal will be used in practice.
Some proposals that have limited external surface area (e.g. add a flag in a function call) may not require this but try to write motivating examples down where possible.
This section is relatively freeform but should remain concise and to the point.
Extraneous details in examples should be omitted (e.g. code examples do not need to compile).

== Issues

This section describes issues with the existing proposal – including both open issues that you have not addressed, and closed issues that are not self-evident from the proposal description.

=== RESOLVED: How are issues written?

Each issue should be a separate subsection starting with a question, an indication of the status (UNRESOLVED/PROPOSED/RESOLVED), discussion expanding on the question, and a proposal for resolving it if there is one.

== Further Functionality

This section is for anything that could be beneficial in the final solution, but may not be necessary to address the core problem.
Subsections here will be like those in section 3 (Proposal) but offer additional background as to what peripheral problem they address, or benefit they provide.
Writing this section is a good chance to re-evaluate if anything can or should be moved from section 3 to here, or just outright removed.