bdk
bdk copied to clipboard
bitcoindevkit
Proposal: Write Architectural Decision Records
This issue will track the discussion around potentially adding Architectural Decision Records (ADRs) to the BDK repository.
I personally learned about them for the first time last year when reading the ADRs for the uniffi project. Their readme defines well what they are useful for:
This directory contains a series of Architectural Decision Records or "ADRs" for the uniffi project. We're going to try to use it as a kind of collective memory of the decisions we've made and the path we've taken to get the project to its current point. Proposing a non-trivial change to the way uniffi works? You might like to start with an ADR by copying template.md into a new file, filling out a first version of the proposal, and posting it as a PR on the github repo for discussion.
The template in question contains section titles prompting the writer to expand on many interesting points for newcomers to the codebase attempting to understand the history of the codebase, the important choices that were made, and why they were made. Section titles include:
- Short title of solved problem and solution
- Date
- Technical Story
- Context and Problem Statement
- Decision Drivers
- Considered Options
- Pros and Cons of the Options
- Decision Outcome
- Links
We have incorporated them (albeit very lightly so far) in the bdk-ffi repository. Even writing out some of those things helped me cement my understanding of why we had done things a certain way and allowed us to open a few PRs to clean up the codebase in order to live by the small ADRs we had written. We'll write more in the future.
Some extra readings on ADR:
- https://www.ozimmer.ch/practices/2023/04/03/ADRCreation.
- https://github.com/joelparkerhenderson/architecture-decision-record
- https://adr.github
- https://betterprogramming.pub/the-ultimate-guide-to-architectural-decision-records-6d74fd3850ee
- https://www.redhat.com/architect/architecture-decision-records
The recent persistence changes (#1473) would be a good candidate for an ADR
As we've been discussing about the Book of BDK, I think ADRs might also contribute by better referencing the decisions behind some specific usage/architecture mentioned in the book, so another +1 to ADRs.
All the discussions/decisions on requiring a change descriptor (#1390), and reverting on it (#1533) would be another great candidate for an ADR.