1// Copyright 2021-2024 The Khronos Group Inc. 2// 3// SPDX-License-Identifier: CC-BY-4.0 4 5= Proposal Template 6:toc: left 7:refpage: https://registry.khronos.org/vulkan/specs/1.3-extensions/man/html/ 8:sectnums: 9 10.How to use this document 11[NOTE] 12==== 13This document outlines the expected flow of a proposal - text in the following sections is there as guidance for how to fill out each section. 14When creating a new proposal, text inside these sections (including this note!) should be removed and replaced with actual proposal text. 15 16Proposal 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. 17 18When calling out existing API constructs or extensions, the `refpage` attribute should be used to link to the relevant Khronos reference page. 19For example - "...used to extend link:{refpage}VkGraphicsPipelineCreateInfo.html[VkGraphicsPipelineCreateInfo]..." 20==== 21 22A short summary of this proposal should be written here. 23 24== Problem Statement 25 26This section should detail the problem that is being addressed as succinctly as possible. 27Usually this comes in three parts: 28 29 . Setting the scene 30 . Bulleted list of problems 31 . (Optional) Describe peripheral issues 32 a. I.e. things this may enable solutions for, but does not directly address. 33 34Writing this section is a good opportunity to make sure you are not overreaching by trying to address too many problems at once. 35 36== Solution Space 37 38This section should briefly describe the options that have been considered (this is a good time to reconsider those options too!). 39 40Start 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. 41 42== Proposal 43 44This 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. 45Typically, this section will be split into subsections describing different areas of the proposal. 46 47This 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). 48They may make it into the final proposal, but it is important to give others the opportunity to evaluate these independently. 49 50== Examples 51 52Where relevant, add one or more examples of how this proposal will be used in practice. 53Some 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. 54This section is relatively freeform but should remain concise and to the point. 55Extraneous details in examples should be omitted (e.g. code examples do not need to compile). 56 57== Issues 58 59This 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. 60 61=== RESOLVED: How are issues written? 62 63Each 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. 64 65== Further Functionality 66 67This section is for anything that could be beneficial in the final solution, but may not be necessary to address the core problem. 68Subsections here will be like those in section 3 (Proposal) but offer additional background as to what peripheral problem they address, or benefit they provide. 69Writing 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. 70