🏗️ support for ADRs/RFDs/RFCs lacks template, guidance, publishing infra, etc.

[DerekNonGeneric]

I owe our entire community an apology. Recently, in an overzealous attempt at efficiency, I deleted a detailed record related to scaling our ADRs without adequately considering the impact. If any of you wish to give input on appropriate amends or share constructive criticism I should hear, please come to me openly. We shall become wiser together.

At the most fundamental level, i will:

• restore/recover the deleted [notes] on this critical engineering issue by day's end (we use pacific time here)
• resolve any blocked progress
• incorporate any updated details provided (playful satire came quickly; reception has been positive/supportive; proposal for @ocaml based stack was fielded & well received)

Consider the record returned in full. ✅

This initial action, however, only partially encompasses the amends entailed. I openly welcome any additional constructive feedback on rectifying my mistakes in judgment - be they replenishments in process, safeguards against repetition, or building renewed understanding. My responsibility in this situation stretches beyond data to trust and respect among teammates. Please come to me freely with thoughts so we may walk this path to redemption together. With open ears, hearts, and minds on all sides, I am confident in our bonds moving forward.

Woo foo!

[DerekNonGeneric]

Note

Just prior to deleting the original issue (#599, notice 404 now), i took a full-page screenshot 🎞️ for safe keeping. Below is my attempt at making a faithful transcription of its content… Small edits were made for clarity.

A decision was made to store ADRs/RFDs in a log in the project repository. [Org-wide decisions would most logically be located here in this repository.] Let's follow along w/ what @oxidecomputer has done by justifying their employment (i.e., routine usage) as a customary practice in [an ADR numbered] 0001…

This will necessitate shifting forward what we currently have as our ADR 001…

This is a good place for these (we have the blog infra already set up^*), but there still needs to be better support for these ADRs/RFDs/RFCs (e.g., a standard way in which they all look as well as enforcement of this standard via Markdown linter). We will not be using AsciiDoc like @oxidecomputer as we're already well-invested in Markdown (to the point of even having started developing our own standard flavor of it). Follow progress on our custom fork of Gherkin Markdown:

🔗：https://github.com/OpenINF/Gherkin-Markdown.

A template would help streamline the production of these engineering documents…

---

i like what @backstage has done to help organize and publish their ADRs:

🔗：https://github.com/backstage/backstage/tree/master/docs/architecture-decisions

---

i like what @oxidecomputer has done to help organize and publish their RFDs:

🔗：https://rfd.shared.oxide.computer/rfd/0001

---

Finally, when it comes to our approach to ADRs, RFDs, RFCs, and other similar documents, we recommend tuning into the informative Oxide Computer podcast episode available at https://youtu.be/wN8lclUKZAU. In this episode, @oxidecomputer provides valuable insights into the process of productizing these documents. It's worth noting that they have already published a significant number of these documents, reaching triple digits. To ensure that we're playing it safe, we suggest padding the incrementing number with enough leading zeros. For instance, a single digit should have three leading zeros, which will future-proof our system.

[DerekNonGeneric]

TIL about the adr-tools project, which were designed to help facilitate this process of creating, maintaining, and consuming ADRs…