xref: /third_party/vk-gl-cts/external/vulkan-docs/src/style/revisions.adoc

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

[appendix]
[[revisions]]
= Revision History

* 2023-11-30 - Update introduction of the <<writing, Writing Style>> chapter
  to recommend following existing language and API design patterms when
  creating new specification language (internal issue 3707).
* 2023-10-22 - Update <<extensions-naming-author-IDs, description of `EXT`
  extensions>>, since some are now being ratified.
* 2023-10-11 - Add rules for <<writing-titlecase, writing chapter and
  section titles>>.
* 2023-10-05 - Mention that <<extensions-reserving-bitmask-values, bit
  position 31>> may not be used for enumerated type bitmasks, due to
  portability concerns.
* 2023-07-07 - Remove style guide requirement to
  <<sample-writing-explicit-vu, not use nested bullet points or other
  complex markup in a valid usage statement>>, which is now allowed due to
  toolchain improvements.
* 2023-07-07 - Add "`use case`" as <<writing-compound-words, preferred
  orthography>> (internal merge request 5991).
* 2023-07-05 - Change the boilerplate language for `sType` to refer to
  `VkStructureType` (internal issue 3493).
* 2023-06-21 - Remove the style guide advice to keep valid usage statements
  "`atomic`" with respect to preprocessor directives, as a recent script and
  validation layer change has enabled preprocessor directives within VUs.
  In its place, add new advice about making sure all version and extension
  information is included in the text of the valid usage statement rather
  than relying on preprocessor directives.
* 2023-05-03 - Add <<markup-word-choices, preferred way to write>> "`called
  _in_ a command buffer`" (internal issue 3480).
* 2023-04-30 - Update <<markup-blocks, Blocks>> to remove tilde markup for
  source blocks inside refpages, and use `[open]`-tagged listing blocks for
  <<markup-blocks-nested-open, continuation blocks inside refpages>>
  instead.
* 2023-02-26 - update description of computing numeric enumerant values, and
  reference the normative references section for the registry schema
  document (public issue 2069).
* 2022-11-29 - Add a NOTE to the <<writing-conventions, Use American
  Spelling Conventions>> section explain why there are a few uses of
  "`colour`" in the Vulkan Video extensions (internal issue 3254).
* 2022-11-16 - Update `basetype` <<markup-macros-api, markup macro>>
  description to exclude types without definitions in the Vulkan
  Specification, such as the Video `Std*` types (internal issue 2703).
* 2022-11-11 - Add <<markup-word-choices, preferred way to write>>
  "`_handle_ is not dlink{cl}VK_NULL_HANDLE`"
* 2022-10-12 - Add <<markup-word-choices, preferred way to write>> "`_verb_
  on the device`", and re-order part of that table (internal merge request
  5475).
* 2022-09-05 - Refactor markup to separate <<introduction, Introduction>>
  chapter from `styleguide.adoc` and make anchor naming scheme consistent.
  Convert <<revisions, Revision History>> from a chapter to an appendix and
  add an anchor.
* 2022-07-14 - Add <<markup-sample-section-features, Feature
  Cross-References>> section specifying how to mark up API feature links.
* 2021-11-21 - Add preferred uses of "`indirect (drawing/dispatching)
  command`" to the <<writing-compound-words, Compound Words and Preferred
  Orthography>> section.
* 2021-11-15 - Add <<markup-include-file-paths, Include File Paths>> section
  requiring using full paths to included markup files.
* 2021-11-04 - Remove backquote markup around recommended use of the
  `apiext:` macro, since that macro now styles the extension name argument
  itself.
* 2021-10-29 - add "`render pass" to the <<writing-compound-words, Compound
  Words and Preferred Orthography>> section.
* 2021-10-04 - Update the <<extensions-documenting-extensions, Changes for
  New Extensions>> section to require use of the `apiext:` macro for links
  to extension names (internal issue 2831).
* 2021-09-12 - Add a new subsection with more details on using
  tilde-delimited source blocks <<markup-blocks-source, inside reference
  page open blocks>>, and rewrite the <<sample-command, Sample Command
  Description>> section to follow current phrasing and markup patterns
  (internal issue 2040).
* 2021-09-09 - Add the <<markup-italicized-enumerant-names, Italicized
  Enumerant Names>> section to clarify how to write wildcard enumerant names
  with imbedded italicized text.
* 2021-09-06 - Add the <<writing-inclusivity, Use Inclusive Language>>
  section based on the Khronos Inclusive Language list (internal issue
  2293).
* 2021-09-06 - add "`cube map`" to the <<writing-compound-words, Compound
  Words and Preferred Orthography>> section (internal merge request 4794).
* 2021-07-20 - Add additional contraction examples to the table in the
  <<markup-avoid-contractions, Avoid Abbreviations and Contractions>>
  section.
* 2021-05-31 - Add "`implementation-dependent`" as an exception in the
  <<writing-compound-words, Compound Words and Preferred Orthography>>
  section (internal merge request 4611).
* 2021-05-24 - Add escapes to prevent expansion of attribute names in a few
  places where markup examples are given.
* 2021-05-22 - Expand the <<markup-avoid-contractions, markup rules>> to
  include avoiding abbreviations, as well as contractions.
* 2021-05-07 - Add <<markup-word-choices, preferred way to write
  "`drawing/dispatching command">>.
* 2021-04-28 - Add <<markup-word-choices, disambiguations for
  "`executable`">>.
* 2021-04-28 - Add <<writing-pointers-instances, usage for pointers and
  handles>> which may be `NULL` or dname:VK_NULL_HANDLE, respectively
  (internal issue 2662).
* 2021-04-14 - Add "`side effect`" and "`reuse`" as
  <<writing-compound-words, preferred orthography>> (public issue 1484).
* 2021-03-31 - Update description of the code{cl} macro in the
  <<markup-macros-api, API Markup Macros>> section to match current
  behavior.
* 2021-03-21 - Note that the <<extensions-reserving-bitmask-values same bit
  should be reserved>> for the same purpose in comparable 32- and 64-bit
  bitmask types (internal issue 2565).
* 2020-09-14 - Change <<markup-informative-notes, Informative Sections and
  Notes>> section to track actual usage and update the description of the
  undefined{cl} macro to further clarify its purpose and uses (internal
  issue 2195).
* 2020-08-16 - Add "`reference monitor`" to the preferred
  <<markup-word-choices, Word Choices>> (internal issue 2291).
* 2020-08-10 - Add a <<writing-describing-errors, Commands which Return
  Error Codes>> section to guide authors of new commands (internal issue
  2290).
* 2020-07-28 - Add a <<markup-copyrights, Copyrights and Licenses>> section
  describing how to properly attribute this information.
* 2020-06-23 - Update the <<extensions-documenting-extensions, Changes for
  New Extensions>> section to recommend placing most extension language
  inline in existing specification source files, rather than in separate
  files, and to base extension revision numbers at `1` starting with initial
  public release (public issue 1263).
* 2020-04-29 - Expand use of `basetype` macros to include external API
  types.
* 2020-03-16 - Add documentation of writing links to extension appendices in
  the <<extensions-documenting-extensions, Changes for New Extensions>>
  section and document the `apiext{cl}` and `reflink{cl}` macros in the
  <<markup-macros-api, API Markup Macros>> section.
  Improve documentation of writing <<writing-refpages, Markup For Automatic
  Reference Page Extraction>> including how to mark up content in the
  Specification source so it only appears in generated reference pages;
  however, this section is still out of date (internal issue 1999).
* 2020-03-11 - Specify in the <<sample-command, Sample Command Description>>
  section that a valid usage statement must be defined at the place (command
  or structure specification) that all information need to evaluate the
  statement is known.
  Update the description of <<appendix-vuid-creating, Creating VUID tags>>
  to match the current scripts.
  Use the term "`asciidoctor`" instead of "`asciidoc`" everywhere.
  Note in the <<introduction-asciidoc, Asciidoctor Markup>> section that the
  Specification can only be built using the command-line asciidoctor client,
  not by asciidoctor web clients.
* 2020-02-22 - Document that it is no longer needed to escape C arrows in
  macros.
* 2019-12-15 - Add a markup section on <<markup-macros-prime-symbols, Prime
  Symbols>> (internal issue 1110).
* 2019-11-27 - Expand the <<writing-pNext-chain, Describing Extension
  Structure Chains>> section and make all spec language consistent with it
  (internal issue 1814).
* 2019-09-09 - Define markup for nested structure members in the
  <<markup-macros-api, API Markup Macros>> section (internal issue 1765).
* 2019-09-08 - Add language to the end of the
  <<extensions-documenting-extensions, Changes for New Extensions>> section
  describing how to mark up asciidoctor conditionals (internal issue 1808).
* 2019-08-25 - Add the <<markup-indentation-equations, Indentation of
  Equations>> section (internal issue 1793).
* 2019-08-25 - Add the <<writing-describing-layers, Extensions and Grouping
  Related Language>> section (internal issue 979) and the
  <<markup-minimize-indentation, Minimize Indentation>> section (internal
  issue 747).
  Disallow use of standalone `+` except in latexmath and source blocks, in
  the <<markup-layout, Asciidoc Markup And Text Layout>> section (internal
  issue 736).
* 2019-08-19 - Add the <<writing-pointers-instances, Describing Pointers and
  Instances>> section (internal issue 1553).
* 2019-08-13 - Add a NOTE to the <<appendix-vuid-format, Format of VUID
  Tags>> appendix specifying allowed characters in VUID tags (based on
  discussion for internal merge request 3239).
* 2019-07-27 - Add the <<writing-references, References>> section and
  rewrite external references accordingly.
* 2019-05-09 - Specify rules for defining <<extensions-new-flags-types, new
  flags and bitmask types>> (internal issue 1649).
* 2019-01-06 - Add details on <<extensions-reserving-bitmask-values,
  Reserving Bitmask Values>> (internal issue 1411).
* 2018-11-19 - Add details to the <<extensions-documenting-extensions,
  Changes for New Extensions>> section including the new "`Description`"
  section, and other standard parts of extension appendices.
* 2018-08-13 - Add %inline directive to the <<markup-sample-section-images,
  Figures>> section (public pull request 734).
* 2018-07-30 - Added a section on <<writing-undefined, Describing Undefined
  Behavior>> (as part of the fixes for public issue 379), and describing why
  the undefined{cl} macro should always be used.
* 2018-07-08 - Remove requirement to explicitly include extension appendices
  in the <<extensions-documenting-extensions, Changes for New Extensions>>
  section.
* 2018-06-25 - Modify the process for <<extensions-vendor-id, Registering a
  Vendor ID with Khronos>> to define vendor ID values as part of an
  enumerated type.
* 2018-03-07 - Updated for Vulkan 1.1 release.
* 2018-01-10 - Move details of mandated extension compatibility from the
  <<extensions-rules, General Rules/Guidelines>> section into the
  Fundamentals section of the API Specification, where they are changed
  slightly to allow explicit incompatibilities (public issue 638).
* 2017-10-27 - Add language about proper use of "`valid pointer`" and
  "`pointer to valid object`" for valid usage statements, in the
  <<sample-command, Sample Command Description>> section (related to public
  pull request 547).
* 2017-10-15 - Describe how to write <<writing-latexmath-in-table-cells,
  LaTeX Math in Table Cells>> (internal issue 908).
* 2017-10-15 - Add more details of <<extensions-naming-author-IDs, `KHX`
  extensions>> (public issues 536, 580).
* 2017-09-10 - Add descriptions of <<writing-arrays, how to use `each` and
  `any`>> to refer to properties of elements of arrays (internal issue 884).
* 2017-09-10 - Add <<extensions-interactions-parent, Valid Usage and
  Extension pname:pNext Chains>> language specifying where to describe
  interactions of structures in a pname:pNext chain (internal issue 715).
* 2017-09-10 - Add example of marking up an enumerated type all of whose
  values are defined by extensions (internal issue 864).
* 2017-08-25 - Add language to the <<extensions,API Versions, Extensions,
  and Layers>> chapter describing how to write new API versions (internal
  issue 892).
* 2017-06-12 - Add sections describing when to use the
  <<markup-macros-api-name, *name{cl}>> and <<markup-macros-api-text,
  *text{cl}>> markup macros instead of the *link{cl} macros, and clarify
  that slink{cl} should be used for handle as well as structure names
  (internal issue 886).
* 2017-05-08 - Add appendix describing <<appendix-vuid, Valid Usage ID
  Tags>> and how they are generated.
* 2017-03-19 - Add naming rule for <<naming-extension-structures, Extension
  Structure Names>>.
* 2017-02-11 - Finish transitioning to asciidoctor markup.
* 2016-09-28 - Add asciidoc math markup guidelines.
* 2016-09-16 - Make style guide markup more consistent with its own
  recommendations.
  Simplify some tables of preferred terms.
  Add sections on block and table markup.
* 2016-09-12 - Describe writing and markup style for labelled lists.
  Require use of the ISO 8601 date format except in rare legacy cases.
  Expand the description of <<markup-layout,Line Lengths>> and add a
  description of markup for <<markup-footnotes,Footnotes>>.
* 2016-09-08 - Add a writing section about proper use of
  <<writing-misc-a-an,"`a`" and "`an`">> (internal issue 432).
* 2016-08-30 - Remove mustnot{cl} and shouldnot{cl} macro definitions, which
  are no longer used in the Specification (internal issue 407).
* 2016-08-29 - Add spelling and compound word rules (public issue 352).
* 2016-08-23 - Modify description of specifying extensions in the
  <<extensions,Layers and Extensions>> chapter to refer to the new
  single-branch model for extensions (internal issue 397).
* 2016-07-26 - Add section describing <<writing-refpages,markup for
  automatic reference page extraction>>.
* 2016-07-18 - Add examples of function-parameter and structure-member
  markup (based on public issue 286).
* 2016-07-11 - Change the document title.
* 2016-07-07 - Rename document, change license to CC BY, clarify required
  and recommended actions, and reserve use of "`normative`" for the
  Specifications.
* 2016-06-26 - Move Layers and Extensions chapter from Appendix C of the
  Vulkan API Specification and merge content with the naming guide.
  Put extension and naming chapters into their own source files.
* 2016-06-20 - Add API naming guide.
* 2016-05-22 - Add markup and image creation rules, after fixing missing
  figure captions for public issue 219.
* 2016-05-01 - Include feedback from public issues 120 and 190.
  Use consistent conventions for defining structures.
  Use American rather than British spelling conventions.
* 2016-03-12 - Recommend against "the value of".
* 2016-02-26 - Replace use of the "maynot{cl}" macro with "may{cl} not".
* 2016-02-16 - Place asciidoc conversion post-release.
* 2016-02-09 - Added quotation mark convention.
* 2016-02-01 - Add the Oxford Comma section and issue resolution.
* 2016-01-26 - Add bullet-list style description of command parameters.
* 2016-01-11 - Add "`Numbers in Text`" section from WSI work.
* 2015-12-16 - Make "`begin / end`" preferred terms to "`start / finish`".
* 2015-12-15 - Make "`implementation`" preferred term instead of "`system`".
* 2015-12-13 - Add tlink{cl}/tname{cl} macros for function pointer types.
* 2015-12-10 - Initial release for feedback.


ifdef::VKSC_VERSION_1_0[]
== Vulkan SC Revision History

* 2019-06-25 - Added <appendix-scid, Safety Critical ID Tags (SCID)>>
  appendix.
endif::VKSC_VERSION_1_0[]