1// Copyright 2014-2024 The Khronos Group Inc. 2// SPDX-License-Identifier: CC-BY-4.0 3 4[appendix] 5[[revisions]] 6= Revision History 7 8* 2023-11-30 - Update introduction of the <<writing, Writing Style>> chapter 9 to recommend following existing language and API design patterms when 10 creating new specification language (internal issue 3707). 11* 2023-10-22 - Update <<extensions-naming-author-IDs, description of `EXT` 12 extensions>>, since some are now being ratified. 13* 2023-10-11 - Add rules for <<writing-titlecase, writing chapter and 14 section titles>>. 15* 2023-10-05 - Mention that <<extensions-reserving-bitmask-values, bit 16 position 31>> may not be used for enumerated type bitmasks, due to 17 portability concerns. 18* 2023-07-07 - Remove style guide requirement to 19 <<sample-writing-explicit-vu, not use nested bullet points or other 20 complex markup in a valid usage statement>>, which is now allowed due to 21 toolchain improvements. 22* 2023-07-07 - Add "`use case`" as <<writing-compound-words, preferred 23 orthography>> (internal merge request 5991). 24* 2023-07-05 - Change the boilerplate language for `sType` to refer to 25 `VkStructureType` (internal issue 3493). 26* 2023-06-21 - Remove the style guide advice to keep valid usage statements 27 "`atomic`" with respect to preprocessor directives, as a recent script and 28 validation layer change has enabled preprocessor directives within VUs. 29 In its place, add new advice about making sure all version and extension 30 information is included in the text of the valid usage statement rather 31 than relying on preprocessor directives. 32* 2023-05-03 - Add <<markup-word-choices, preferred way to write>> "`called 33 _in_ a command buffer`" (internal issue 3480). 34* 2023-04-30 - Update <<markup-blocks, Blocks>> to remove tilde markup for 35 source blocks inside refpages, and use `[open]`-tagged listing blocks for 36 <<markup-blocks-nested-open, continuation blocks inside refpages>> 37 instead. 38* 2023-02-26 - update description of computing numeric enumerant values, and 39 reference the normative references section for the registry schema 40 document (public issue 2069). 41* 2022-11-29 - Add a NOTE to the <<writing-conventions, Use American 42 Spelling Conventions>> section explain why there are a few uses of 43 "`colour`" in the Vulkan Video extensions (internal issue 3254). 44* 2022-11-16 - Update `basetype` <<markup-macros-api, markup macro>> 45 description to exclude types without definitions in the Vulkan 46 Specification, such as the Video `Std*` types (internal issue 2703). 47* 2022-11-11 - Add <<markup-word-choices, preferred way to write>> 48 "`_handle_ is not dlink{cl}VK_NULL_HANDLE`" 49* 2022-10-12 - Add <<markup-word-choices, preferred way to write>> "`_verb_ 50 on the device`", and re-order part of that table (internal merge request 51 5475). 52* 2022-09-05 - Refactor markup to separate <<introduction, Introduction>> 53 chapter from `styleguide.adoc` and make anchor naming scheme consistent. 54 Convert <<revisions, Revision History>> from a chapter to an appendix and 55 add an anchor. 56* 2022-07-14 - Add <<markup-sample-section-features, Feature 57 Cross-References>> section specifying how to mark up API feature links. 58* 2021-11-21 - Add preferred uses of "`indirect (drawing/dispatching) 59 command`" to the <<writing-compound-words, Compound Words and Preferred 60 Orthography>> section. 61* 2021-11-15 - Add <<markup-include-file-paths, Include File Paths>> section 62 requiring using full paths to included markup files. 63* 2021-11-04 - Remove backquote markup around recommended use of the 64 `apiext:` macro, since that macro now styles the extension name argument 65 itself. 66* 2021-10-29 - add "`render pass" to the <<writing-compound-words, Compound 67 Words and Preferred Orthography>> section. 68* 2021-10-04 - Update the <<extensions-documenting-extensions, Changes for 69 New Extensions>> section to require use of the `apiext:` macro for links 70 to extension names (internal issue 2831). 71* 2021-09-12 - Add a new subsection with more details on using 72 tilde-delimited source blocks <<markup-blocks-source, inside reference 73 page open blocks>>, and rewrite the <<sample-command, Sample Command 74 Description>> section to follow current phrasing and markup patterns 75 (internal issue 2040). 76* 2021-09-09 - Add the <<markup-italicized-enumerant-names, Italicized 77 Enumerant Names>> section to clarify how to write wildcard enumerant names 78 with imbedded italicized text. 79* 2021-09-06 - Add the <<writing-inclusivity, Use Inclusive Language>> 80 section based on the Khronos Inclusive Language list (internal issue 81 2293). 82* 2021-09-06 - add "`cube map`" to the <<writing-compound-words, Compound 83 Words and Preferred Orthography>> section (internal merge request 4794). 84* 2021-07-20 - Add additional contraction examples to the table in the 85 <<markup-avoid-contractions, Avoid Abbreviations and Contractions>> 86 section. 87* 2021-05-31 - Add "`implementation-dependent`" as an exception in the 88 <<writing-compound-words, Compound Words and Preferred Orthography>> 89 section (internal merge request 4611). 90* 2021-05-24 - Add escapes to prevent expansion of attribute names in a few 91 places where markup examples are given. 92* 2021-05-22 - Expand the <<markup-avoid-contractions, markup rules>> to 93 include avoiding abbreviations, as well as contractions. 94* 2021-05-07 - Add <<markup-word-choices, preferred way to write 95 "`drawing/dispatching command">>. 96* 2021-04-28 - Add <<markup-word-choices, disambiguations for 97 "`executable`">>. 98* 2021-04-28 - Add <<writing-pointers-instances, usage for pointers and 99 handles>> which may be `NULL` or dname:VK_NULL_HANDLE, respectively 100 (internal issue 2662). 101* 2021-04-14 - Add "`side effect`" and "`reuse`" as 102 <<writing-compound-words, preferred orthography>> (public issue 1484). 103* 2021-03-31 - Update description of the code{cl} macro in the 104 <<markup-macros-api, API Markup Macros>> section to match current 105 behavior. 106* 2021-03-21 - Note that the <<extensions-reserving-bitmask-values same bit 107 should be reserved>> for the same purpose in comparable 32- and 64-bit 108 bitmask types (internal issue 2565). 109* 2020-09-14 - Change <<markup-informative-notes, Informative Sections and 110 Notes>> section to track actual usage and update the description of the 111 undefined{cl} macro to further clarify its purpose and uses (internal 112 issue 2195). 113* 2020-08-16 - Add "`reference monitor`" to the preferred 114 <<markup-word-choices, Word Choices>> (internal issue 2291). 115* 2020-08-10 - Add a <<writing-describing-errors, Commands which Return 116 Error Codes>> section to guide authors of new commands (internal issue 117 2290). 118* 2020-07-28 - Add a <<markup-copyrights, Copyrights and Licenses>> section 119 describing how to properly attribute this information. 120* 2020-06-23 - Update the <<extensions-documenting-extensions, Changes for 121 New Extensions>> section to recommend placing most extension language 122 inline in existing specification source files, rather than in separate 123 files, and to base extension revision numbers at `1` starting with initial 124 public release (public issue 1263). 125* 2020-04-29 - Expand use of `basetype` macros to include external API 126 types. 127* 2020-03-16 - Add documentation of writing links to extension appendices in 128 the <<extensions-documenting-extensions, Changes for New Extensions>> 129 section and document the `apiext{cl}` and `reflink{cl}` macros in the 130 <<markup-macros-api, API Markup Macros>> section. 131 Improve documentation of writing <<writing-refpages, Markup For Automatic 132 Reference Page Extraction>> including how to mark up content in the 133 Specification source so it only appears in generated reference pages; 134 however, this section is still out of date (internal issue 1999). 135* 2020-03-11 - Specify in the <<sample-command, Sample Command Description>> 136 section that a valid usage statement must be defined at the place (command 137 or structure specification) that all information need to evaluate the 138 statement is known. 139 Update the description of <<appendix-vuid-creating, Creating VUID tags>> 140 to match the current scripts. 141 Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere. 142 Note in the <<introduction-asciidoc, Asciidoctor Markup>> section that the 143 Specification can only be built using the command-line asciidoctor client, 144 not by asciidoctor web clients. 145* 2020-02-22 - Document that it is no longer needed to escape C arrows in 146 macros. 147* 2019-12-15 - Add a markup section on <<markup-macros-prime-symbols, Prime 148 Symbols>> (internal issue 1110). 149* 2019-11-27 - Expand the <<writing-pNext-chain, Describing Extension 150 Structure Chains>> section and make all spec language consistent with it 151 (internal issue 1814). 152* 2019-09-09 - Define markup for nested structure members in the 153 <<markup-macros-api, API Markup Macros>> section (internal issue 1765). 154* 2019-09-08 - Add language to the end of the 155 <<extensions-documenting-extensions, Changes for New Extensions>> section 156 describing how to mark up asciidoctor conditionals (internal issue 1808). 157* 2019-08-25 - Add the <<markup-indentation-equations, Indentation of 158 Equations>> section (internal issue 1793). 159* 2019-08-25 - Add the <<writing-describing-layers, Extensions and Grouping 160 Related Language>> section (internal issue 979) and the 161 <<markup-minimize-indentation, Minimize Indentation>> section (internal 162 issue 747). 163 Disallow use of standalone `+` except in latexmath and source blocks, in 164 the <<markup-layout, Asciidoc Markup And Text Layout>> section (internal 165 issue 736). 166* 2019-08-19 - Add the <<writing-pointers-instances, Describing Pointers and 167 Instances>> section (internal issue 1553). 168* 2019-08-13 - Add a NOTE to the <<appendix-vuid-format, Format of VUID 169 Tags>> appendix specifying allowed characters in VUID tags (based on 170 discussion for internal merge request 3239). 171* 2019-07-27 - Add the <<writing-references, References>> section and 172 rewrite external references accordingly. 173* 2019-05-09 - Specify rules for defining <<extensions-new-flags-types, new 174 flags and bitmask types>> (internal issue 1649). 175* 2019-01-06 - Add details on <<extensions-reserving-bitmask-values, 176 Reserving Bitmask Values>> (internal issue 1411). 177* 2018-11-19 - Add details to the <<extensions-documenting-extensions, 178 Changes for New Extensions>> section including the new "`Description`" 179 section, and other standard parts of extension appendices. 180* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images, 181 Figures>> section (public pull request 734). 182* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined 183 Behavior>> (as part of the fixes for public issue 379), and describing why 184 the undefined{cl} macro should always be used. 185* 2018-07-08 - Remove requirement to explicitly include extension appendices 186 in the <<extensions-documenting-extensions, Changes for New Extensions>> 187 section. 188* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a 189 Vendor ID with Khronos>> to define vendor ID values as part of an 190 enumerated type. 191* 2018-03-07 - Updated for Vulkan 1.1 release. 192* 2018-01-10 - Move details of mandated extension compatibility from the 193 <<extensions-rules, General Rules/Guidelines>> section into the 194 Fundamentals section of the API Specification, where they are changed 195 slightly to allow explicit incompatibilities (public issue 638). 196* 2017-10-27 - Add language about proper use of "`valid pointer`" and 197 "`pointer to valid object`" for valid usage statements, in the 198 <<sample-command, Sample Command Description>> section (related to public 199 pull request 547). 200* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells, 201 LaTeX Math in Table Cells>> (internal issue 908). 202* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX` 203 extensions>> (public issues 536, 580). 204* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and 205 `any`>> to refer to properties of elements of arrays (internal issue 884). 206* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and 207 Extension pname:pNext Chains>> language specifying where to describe 208 interactions of structures in a pname:pNext chain (internal issue 715). 209* 2017-09-10 - Add example of marking up an enumerated type all of whose 210 values are defined by extensions (internal issue 864). 211* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions, 212 and Layers>> chapter describing how to write new API versions (internal 213 issue 892). 214* 2017-06-12 - Add sections describing when to use the 215 <<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text, 216 *text{cl}>> markup macros instead of the *link{cl} macros, and clarify 217 that slink{cl} should be used for handle as well as structure names 218 (internal issue 886). 219* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID 220 Tags>> and how they are generated. 221* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension 222 Structure Names>>. 223* 2017-02-11 - Finish transitioning to asciidoctor markup. 224* 2016-09-28 - Add asciidoc math markup guidelines. 225* 2016-09-16 - Make style guide markup more consistent with its own 226 recommendations. 227 Simplify some tables of preferred terms. 228 Add sections on block and table markup. 229* 2016-09-12 - Describe writing and markup style for labelled lists. 230 Require use of the ISO 8601 date format except in rare legacy cases. 231 Expand the description of <<markup-layout,Line Lengths>> and add a 232 description of markup for <<markup-footnotes,Footnotes>>. 233* 2016-09-08 - Add a writing section about proper use of 234 <<writing-misc-a-an,"`a`" and "`an`">> (internal issue 432). 235* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which 236 are no longer used in the Specification (internal issue 407). 237* 2016-08-29 - Add spelling and compound word rules (public issue 352). 238* 2016-08-23 - Modify description of specifying extensions in the 239 <<extensions,Layers and Extensions>> chapter to refer to the new 240 single-branch model for extensions (internal issue 397). 241* 2016-07-26 - Add section describing <<writing-refpages,markup for 242 automatic reference page extraction>>. 243* 2016-07-18 - Add examples of function-parameter and structure-member 244 markup (based on public issue 286). 245* 2016-07-11 - Change the document title. 246* 2016-07-07 - Rename document, change license to CC BY, clarify required 247 and recommended actions, and reserve use of "`normative`" for the 248 Specifications. 249* 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the 250 Vulkan API Specification and merge content with the naming guide. 251 Put extension and naming chapters into their own source files. 252* 2016-06-20 - Add API naming guide. 253* 2016-05-22 - Add markup and image creation rules, after fixing missing 254 figure captions for public issue 219. 255* 2016-05-01 - Include feedback from public issues 120 and 190. 256 Use consistent conventions for defining structures. 257 Use American rather than British spelling conventions. 258* 2016-03-12 - Recommend against "the value of". 259* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not". 260* 2016-02-16 - Place asciidoc conversion post-release. 261* 2016-02-09 - Added quotation mark convention. 262* 2016-02-01 - Add the Oxford Comma section and issue resolution. 263* 2016-01-26 - Add bullet-list style description of command parameters. 264* 2016-01-11 - Add "`Numbers in Text`" section from WSI work. 265* 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`". 266* 2015-12-15 - Make "`implementation`" preferred term instead of "`system`". 267* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types. 268* 2015-12-10 - Initial release for feedback. 269 270 271ifdef::VKSC_VERSION_1_0[] 272== Vulkan SC Revision History 273 274* 2019-06-25 - Added <appendix-scid, Safety Critical ID Tags (SCID)>> 275 appendix. 276endif::VKSC_VERSION_1_0[] 277