diff --git a/errata/README.md b/errata/README.md index d47c862787..33b0776776 100644 --- a/errata/README.md +++ b/errata/README.md @@ -30,14 +30,45 @@ The level 2 heading in the top-level section for each previous version should us ## Erratum format Each erratum should be in the following format -(replacing `YYYY-MM-DD`, `Section Title`, and `details of what happened`): +(replacing `YYYY-MM-DD`, `Section Title`, `details of changes`, and `#NNNN`): ```html -
  • YYYY-MM-DD: In Section Title, details of what happened.
  • +
  • + YYYY-MM-DD: + In Section Title, + details of changes. + ({% gh #NNNN %}) +
  • ``` Adhering to this format is important, as any entries under the latest published version will also be parsed for inclusion within Guideline/SC boxes and Key Terms definitions within Understanding pages. +(Newlines are insignificant and are suggested for source code readability.) + +Each piece of this format is further explained in the subsections below. + +### Section reference + +When applicable, errata should begin with an indication of the section they relate to, including a link. + +Example phrasing when linking to a section, e.g. a success criterion: + +```html +In 2.5.8 Target Size (Minimum) +``` + +Example phrasing when linking to a term definition: + +```html +In the definition for single pointer +``` + +(Remember that term definition fraagments always begin with `dfn-`.) + +It is possible to reference multiple sections/terms from one erratum, +so long as all of the links remain front-loaded prior to the erratum's details. + +### Details of changes `details of what happened` should be expressed in present progressive tense (e.g. "updating", "removing", "adding"), with the desired outcome listed first. @@ -47,3 +78,16 @@ For example: - removing one note and adding two new notes, including ... - removing a supernumary "Note" indicator from the first note. - correcting the word ... to ... + +### GitHub PR or commit + +When possible, provide a reference to one or more GitHub pull requests or commit hashes +at the end of each erratum, in the format `({% gh "..." %})`. + +The format breaks down as follows: + +- `{% gh "..." %}` is a custom shortcode, which accepts one of the following: + - A PR number prefixed with `#`, e.g. `"#4080"` (this is the preferred option when available) + - A commit hash of 7 or more characters, with no prefix, e.g. `"b043430"` +- The quotes around the parameter passed to the `gh` shortcode are necessary for template parsing +- The outer parentheses exist only for punctuation, and are directly output