ArchDoc Design record
ArchDoc
ADR-0023 Accepted

Every finding no permitted edit can clear is a warning

Comparing
v2 to v3
Current
Read the document

Context

ADR-0009 makes a finding that no permitted edit to the named document could clear a warning, and applies it to the rules whose subject is the document's own body, naming L14, L16 and L17. The rules added since that read a body, L20 and L21, follow it. Nine others report faults that only an edit to a frozen document could clear, and under ADR-0001 that edit is never permitted:

Rule A fault it reports in a frozen document
L01 A required front matter key missing, or a value of the wrong type
L02 An id differing from the identifier the filename gives
L03 An identifier held by another document, where every document holding it is frozen
L04 A ref named in depends or includes, or a reference that is not an identifier any document can hold, such as foo, rfc-0001 or ADR-0000
L05 The document itself, a document of another type, or one document in both updates and obsoletes; or a frozen target that is not accepted
L07 A decided date before created
L08 A required section missing or out of order
L09 Anything left under Open questions in an accepted document
L10 An H1 differing from the title

Each stays an error, so lint fails on that repository for good. L08, L09 and L10 read the body, and ADR-0009's list omits them. L01, L02 and L07 read the front matter, which ADR-0009's scope does not reach. L03, L04 and L05 report relationships, which ADR-0009 sets aside as cleared by editing the other document, but no edit to another document clears these: a type comes from the identifier, a frozen target keeps its status, a frozen document cannot be renumbered, and no document can be written to hold what is not an identifier. RFC-0009 describes L08's finding of a level two heading after the closing section as an error that does not soften. In a frozen document it is a fault no permitted edit can clear.

The gap in the body and the front matter was raised on in #30, and the relationship faults on , while the change in #53 was open.

Decision

A finding that no permitted edit could clear is a warning, whatever part of the document it concerns. When the named document is frozen this applies to L01, L02, L07, L08, L09, L10, L14, L16, L17, L20 and L21; to L04 where it names a ref in depends or includes, or a reference that is not an identifier any document can hold; and to L05 where it names itself, a document of another type, or one document in both lists, or names a frozen target that is not accepted. It applies to L03 where every document holding the identifier is frozen. It does not apply to a fault another permitted edit can clear: a reference to a valid identifier no document holds, whose document can be written; a target that is not accepted and not frozen; or an identifier also held by a document that is not frozen, which can be renumbered. Nor does it apply to L11, whose finding is that a frozen document was edited and whose remedy is to revert.

Alternatives

  • The body rules alone. L08, L09 and L10 become warnings and L01, L02 and L07 stay errors, as ADR-0009's scope gives it. A front matter fault in a frozen document is as permanent as a body fault, so this keeps the failure ADR-0009 was written to remove.
  • Relationship faults left as errors, as ADR-0009 sets them aside. L03, L04 and L05 stay errors in a frozen document. No edit to another document clears the faults in the table above, so this keeps the failure for them.

No other alternatives were weighed.

Consequences

Easier:

  • A repository holding a frozen document with any fault in it will still pass lint, and the fault will still be reported.
  • A finding in a frozen document will be an error only where some permitted edit could clear it.

Harder:

  • More of what lint prints will be warnings that can never be cleared.

Constrained:

  • A rule added later will report a warning wherever its finding could only be cleared by editing a frozen document.

Source adr/0023-every-finding-no-permitted-edit-can-clear-is-a-warning.md · commit aa43057 · published