Document metadata

Authorities

Authors: juh

Owners: juh

Reviews

This document has never been reviewed.

Dependencies

This document does not strictly depend on any others.

Scope of authority

Every document under https://juh.gay/ops/ is in scope of this document. All other documents are not in scope.

Document status definitions

Every document MUST bear exactly one of these badges, OR draft and obsolete together:

draft status indicates that a document is still in its creation phase, has not been reviewed for correctness, and may be (is probably) incomplete. These documents SHOULD NOT be executed (except for testing) and MUST NOT be referenced as sources of truth.

review status indicates that the author thinks the document may be complete, but it needs review by a second person to ensure correctness. These documents SHOULD NOT be executed and SHOULD NOT be referenced as sources of truth.

approved status means that this document is believed to be complete and correct and has passed any reviews that the author deemed necessary. These documents MUST be treated as sources of truth for operations at in-scope facilities (namely, juh’s bedroom lab). If you are a third-party reader intending to use these documents, you SHOULD NOT treat these as sources of truth, and SHOULD conduct additional review of all information you wish to use. Please review the various disclaimers.

deprecated means that this document is planned for obsoletion, but MAY still be executed and treated as a source of truth, until and unless it is superseded by a document with the approved status, at which point the deprecated document SHOULD NOT be executed or treated as a source of truth. Documents with this status SHOULD be annotated with an explanation of why they are deprecated, relevant obsoletion timelines, and any superseding documents available.

obsolete means that the document is no longer canonical. These documents MUST NOT be executed or treated as sources of truth. These documents MAY be annotated with an explanation of why they are obsolete, and SHOULD link to any documents that supersede them. These documents are considered “irredeemable” and cannot leave the obsolete state. If information in an obsolete document is once again needed, it must be recreated in a new draft and receive standard treatment.

A document MAY be tagged as both draft and obsolete at the same time. This use case is intended for abandoned drafts.

Generally, these badges SHOULD be generated by the Pandoc system that converts the source markdown to HTML. Editors SHOULD only need to update the metadata block at the top of the document, not insert badges manually.

State machine

• A document in draft status may:
  • (Owner) Be sent to review.
  • (Owner) Be marked as obsolete.
• A document in review may:
  • (Author, reviewer) Be rejected by the author or reviewer, sending it back to draft status.
  • (Reviewer) Be approved by the reviewer.
• An approved document may:
  • (Author) Receive minor edits and be republished without review.
  • (Author) Receive major edits and be sent back to review.
  • (Owner) Become deprecated and planned for obsoletion.
• A deprecated document may:
  • (Owner) Be sent back to review to see if it can be made relevant again.
  • (Owner) Become obsolete once ALL documents that depend on it have had those dependencies removed.
• An obsolete document MUST remain obsolete, forever. Its contents may be recycled in a new draft, but that must be a separate document with its own history.

Review procedure

A reviewer SHOULD have any expertise necessary to make informed decisions about the content of the documents they review. In some cases this is not possible, and discretion must be used. Sometimes it’s okay to say “two reasonable people thought this looked reasonable”, and other times it’s better to say “this thing will be stuck as a draft until we meet someone who knows what they’re doing”.

Initiating a review (author)

To send a document to review, the author takes these steps:

1. Change the status in the document’s metadata block to review.

2. Create an issue on the site’s GitHub using the review template.

3. Add the review to the reviews list in the metadata block, omitting the reviewer’s name:

   reviews:
   - name: 
     date: 2023-04-30
     status:
       ongoing: yes
     link: https://github.com/juh2600/juh.gay/issues/14

Executing a review (reviewer)

To execute a review, the reviewer assigns the issue to themselves, puts their name in the review log entry, then takes these steps:

1. Read through the entire document.
2. If there are any typographical or content errors or concerns, list them in comments in the review issue created by the author, and assign the issue back to the author.
3. When the reviewer has no more concerns, edit the metadata block and issue:
   1. Change the document status to approved.
   2. Change the review’s status field to pass.
   3. Close the issue as resolved.

Responding to review feedback (author)

When the reviewer leaves comments and assigns the issue back to the author, the author takes these steps:

1. Read and understand all comments left by the reviewer.
2. Make any changes necessary to address the reviewer’s concerns.
3. Discuss and respond to any concerns that do not require changes to the document.
4. Assign the issue back to the reviewer.

These actions cycle back and forth between the author and the reviewer until the issue is closed.

Rejecting a review (author or reviewer)

At any point between opening and closing the issue, either the reviewer or the author MAY decide that the document is not ready to complete a review, because it needs significant work. Either party MAY unilaterally send the document back to draft status, by taking these actions:

1. If a review entry has been added to the document’s metadata block, change the status of the review to abort if done by the author, or fail if done by the reviewer.
2. Change the status of the document to draft in the metadata block.
3. Explain the reasoning for moving the document back to draft in the issue.
4. Close the issue as wontfix.

Deprecation

Any owner of a document may choose to deprecate an approved document at any time, by changing the status of the document to deprecated in the metadata block. This action SHOULD be accompanied by the addition of these fields to the metadata:

deprecation:
  reason: An explanation of why this document has been deprecated and is planned for obsoletion.
  obsoletion-target-date: 2020-04-20
  successors: [no, (list of links)]

While these fields are meant to be helpful, they MAY be omitted. Do your best!

Obsoletion

A document MUST NOT be marked obsolete until a thorough audit has concluded that no other documents depend on it. A description of the audit’s methodology and findings MUST be submitted in the extended commit message on a commit that marks a document as obsolete.

Any owner of a draft or deprecated document may choose to mark that document as obsolete, by changing the status of the document to obsolete in the metadata block. This action SHOULD be accompanied by the addition of these fields to the metadata:

obsoletion:
  reason: An explanation of why this document is obsolete.
  date: 2020-04-20
  successors: [no, (list of links)]

While these fields are meant to be helpful, they MAY be omitted. Only this metadata may be changed after the document is marked as obsolete; the rest of the document (including its other metadata) MUST NOT be modified.

Document header format

By default, all dates must be written in ISO 8601 extended format: YYYY-MM-DD.

Any documents that a document depends on, internal or external, MUST be linked in the dependencies section of the header. Two exceptions to this rule are /advice/disclaimers.md and /ops/doc-status.md, since these are covered by the disclaimers and status fields, respectively.

This is the header format for any document in scope:

---
title: Sample document title
date: 2023-04-01
authors:
- juh
owners:
- juh
reviews:
- name: jes
  date: 2023-04-30
  status:
    ongoing: yes
  link: https://github.com/juh2600/juh.gay/issues/14
- name: juh
  date: 2023-03-05
  status:
    fail: yes
  link: https://github.com/juh2600/juh.gay/issues/14
dependencies:
- /dev/null.md
- https://example.com
disclaimers:
  general: yes
status:
  review: yes
---

Disclaimers and status (both document and review level) are kind of goofy because Pandoc’s template conditionals only know how to discern whether a key is present or absent; there are no comparisons to be made (SO answer about this). I’m getting that feeling that I’m using the wrong tool for the job.

Magic words

Some metadata fields are constrained to a few possible values, listed here:

status: [draft, review, approved, deprecated, obsolete, obsolete-draft]
disclaimers: [general, hazmat, legal, money] # any of the anchored sections in /advice/disclaimers.md should be ok, although they need to be defined in build/inject-doc-metadata.html
reviews: [no, (list of reviews)]
reviews[].status: [ongoing, pass, fail, abort]
dependencies: [no, (list of links)]

These magic words are recognized by the Pandoc templates in build/ that use the metadata block to produce HTML. For lists such as reviews and dependencies, mark no instead of leaving the value empty to have a message generated in the output that indicates there is nothing to show there.