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