Add related ADRs to each other

carbolymer · carbolymer · commit 1fecb2301aaa · 2026-02-24T17:12:55.000+01:00
diff --git a/docs/ADR-001-Default-eras-for-CLI-commands.md b/docs/ADR-001-Default-eras-for-CLI-commands.md
@@ -53,4 +53,9 @@ For example, given the hard fork from Alonzo to Babbage:
 * Users will not be surprised by difference in behaviour between different commands.
 * Users will not necessarily be using the current era by default.
 * Users will be using a most practical current era by default on Mainnet and other networks that may not be on the same era as Mainnet.
-* Users will need to explicitly specify the current era after a hard fork and before the release immediately following the hard for if that's what they really want and at their own risk.
+* Users will need to explicitly specify the current era after a hard fork and before the release immediately following the hard for if that's what they really want and at their own risk.
+
+# Related ADRs
+
+- [ADR-004](ADR-004-Support-only-for-mainnet-and-upcoming-eras.md) limits the eras exposed by `cardano-api` to mainnet and upcoming only.
+- [ADR-012](ADR-012-standardise-CLI-multiple-choice-flags-construction.md) standardises how CLI choice flags (including era flags) should be constructed.
diff --git a/docs/ADR-003-Dependencies-version-constraints-in-cabal-file.md b/docs/ADR-003-Dependencies-version-constraints-in-cabal-file.md
@@ -92,4 +92,8 @@ This will allow for less error-prone dependency management.
 1. [Per-cabal-file `constraints` - Issue in haskell/cabal](https://github.com/haskell/cabal/issues/8912)
 1. https://input-output-hk.github.io/cardano-engineering-handbook/policy/haskell/packaging/versioning.html
 
+# Related ADRs
+
+- [ADR-006](ADR-006-Using-optparse-applicative-main-repository.md) (rejected) — the `optparse-applicative` fork is a concrete example of fork dependency constraints.
+
 
diff --git a/docs/ADR-004-Support-only-for-mainnet-and-upcoming-eras.md b/docs/ADR-004-Support-only-for-mainnet-and-upcoming-eras.md
@@ -168,3 +168,10 @@ The ADR gets adopted in `cardano-api` and `cardano-cli`. There may be minor twea
 # References
 - 1: [ShelleyBasedEra](https://github.com/IntersectMBO/cardano-api/blob/873397bfe0436c224c593f456a3bc237ee0af0c8/cardano-api/internal/Cardano/Api/Eon/ShelleyBasedEra.hs#L123)
 - 2: [CardanoEra](https://github.com/IntersectMBO/cardano-api/blob/873397bfe0436c224c593f456a3bc237ee0af0c8/cardano-api/internal/Cardano/Api/Eras/Core.hs#L256)
+
+# Related ADRs
+
+- [ADR-001](ADR-001-Default-eras-for-CLI-commands.md) defines how CLI commands default to an era.
+- [ADR-009](ADR-009-cardano-api-exports-convention.md) defines the `Cardano.Api.Experimental` and `Cardano.Api.Compatible` module structure.
+- [ADR-010](ADR-010-cardano-api-script-witness-api.md) — the script witness API is parameterized by these eras.
+- [ADR-015](ADR-015-Cardano-API-WASM-library-for-browser.md) — the WASM API exposes only the eras defined here.
diff --git a/docs/ADR-005-cardano-testnet-node-configuration-file.md b/docs/ADR-005-cardano-testnet-node-configuration-file.md
@@ -36,3 +36,7 @@ However, moving the `NodeConfiguration` type and its accompanying types to `card
 # Consequences
 
 This will allow users of testnets to check their node configuration file before starting their testnet, and so they will catch errors earlier and faster.
+
+# Related ADRs
+
+- [ADR-007](ADR-007-CLI-Output-Presentation.md) — CLI output conventions (stdout vs stderr) apply to this command.
diff --git a/docs/ADR-006-Using-optparse-applicative-main-repository.md b/docs/ADR-006-Using-optparse-applicative-main-repository.md
@@ -68,3 +68,8 @@ The changes in the rendered help are still detrimental to the help text readabil
 * [Our 2021 PR](https://github.com/pcapriotti/optparse-applicative/pull/428) to `optparse-applicative`'s main repo.
 * [Our fork](https://github.com/input-output-hk/optparse-applicative) of optparse-applicative.
 * [Our 2024 PR](https://github.com/pcapriotti/optparse-applicative/pull/494) to `optparse-applicative`'s main repo.
+
+# Related ADRs
+
+- [ADR-012](ADR-012-standardise-CLI-multiple-choice-flags-construction.md) standardises CLI flag construction, which relies on the fork this ADR attempted to replace.
+- [ADR-013](ADR-013-Metavars-must-follow-screaming-snake-case.md) defines metavar naming conventions for the help text produced by the fork.
diff --git a/docs/ADR-007-CLI-Output-Presentation.md b/docs/ADR-007-CLI-Output-Presentation.md
@@ -36,3 +36,8 @@ This will require updating them to make things consistent across all the command
 [unix-philosophy]: https://en.wikipedia.org/wiki/Unix_philosophy
 [bell-journal]: https://archive.org/details/bstj57-6-1899/mode/2up
 
+# Related ADRs
+
+- [ADR-005](ADR-005-cardano-testnet-node-configuration-file.md) introduces a new CLI command that should follow these output conventions.
+- [ADR-008](ADR-008-Use-RIO-in-cardano‐cli.md) addresses error handling and rendering in `cardano-cli`.
+
diff --git a/docs/ADR-008-Use-RIO-in-cardano‐cli.md b/docs/ADR-008-Use-RIO-in-cardano‐cli.md
@@ -183,3 +183,8 @@ The purpose of `CustomCliException` is to represent explicitly thrown, structure
 - This should dramatically improve our code's composability and remove many unnecessary error types. 
 - Readability concerning what errors can be thrown will be negatively impacted. However, `ExceptT` already lies about what exceptions can be thrown because it is not limited to the error type stated in `ExceptT`'s type signature. In other words, `IO` can implicitly throw other `Exception`s. 
 - Initially, this will be adopted under the "compatible" group of commands so `cardano-cli` will have a design split temporarily. Once we are happy with the result we will propagate to the rest of `cardano-cli`
+
+# Related ADRs
+
+- [ADR-007](ADR-007-CLI-Output-Presentation.md) defines CLI output stream conventions (stdout vs stderr).
+- [ADR-011](ADR-011-Better-call-stacks-of-io-exceptions.md) extends this ADR with better call stacks for IO exceptions.
diff --git a/docs/ADR-009-cardano-api-exports-convention.md b/docs/ADR-009-cardano-api-exports-convention.md
@@ -90,3 +90,10 @@ This however depends on the specific use case.
 
 Acceptance of ADR will require rename of almost all cardano-api modules which will be a breaking change.
 
+# Related ADRs
+
+- [ADR-002](ADR-002-Module-structure-for-generators.md) defines generator module conventions (`Test.Gen.[Path]`, etc.).
+- [ADR-004](ADR-004-Support-only-for-mainnet-and-upcoming-eras.md) defines the eras exposed through `Cardano.Api.Experimental` and `Cardano.Api.Compatible`.
+- [ADR-010](ADR-010-cardano-api-script-witness-api.md) introduces new types that should be exported following these conventions.
+- [ADR-014](ADR-014-Total-conversion-functions-conventions.md) — placement of `Inject`/`Convert` instances should follow the module conventions defined here.
+
diff --git a/docs/ADR-010-cardano-api-script-witness-api.md b/docs/ADR-010-cardano-api-script-witness-api.md
@@ -261,3 +261,8 @@ Acceptance of this ADR will:
 - Improve the clarity of the witness and script apis
 - Make clearer the relationship between the redeemer pointers and the script witnesses
 - Allow us to use the new api "under the hood" of the old api reducing the maintenance burden of maintaining the old vs new api.
+
+# Related ADRs
+
+- [ADR-004](ADR-004-Support-only-for-mainnet-and-upcoming-eras.md) defines the available eras that parameterize the witness API.
+- [ADR-014](ADR-014-Total-conversion-functions-conventions.md) — conversions between `cardano-api` and `cardano-ledger` types should use `Inject`/`Convert`.
diff --git a/docs/ADR-011-Better-call-stacks-of-io-exceptions.md b/docs/ADR-011-Better-call-stacks-of-io-exceptions.md
@@ -7,7 +7,7 @@
 This ADR enriches exceptions thrown from `IO` functions with call stacks up to the function usage site.
 
 ## The problem
-This ADR bases on [[ADR-8-Use-RIO-in-cardano‐cli]].
+This ADR extends [ADR-008](ADR-008-Use-RIO-in-cardano‐cli.md).
 
 The goal of this ADR is to provide better call stacks in `IO` exceptions.
 The problem with exceptions thrown from IO monad is that they do not carry call stack from where they were thrown.
diff --git a/docs/ADR-012-standardise-CLI-multiple-choice-flags-construction.md b/docs/ADR-012-standardise-CLI-multiple-choice-flags-construction.md
@@ -232,3 +232,8 @@ pQueryUTxOCmd era envCli =
 * *Migration effort*: Existing commands must be updated to the new `Vary` + `Flag` approach.
 * *Learning curve*: Contributors will need to understand how `Flag`, `Vary`, and `setDefault` work.
 * *Breaking changes*: Some commands may behave differently after adopting this change.
+
+# Related ADRs
+
+- [ADR-006](ADR-006-Using-optparse-applicative-main-repository.md) (rejected) — the `optparse-applicative` fork used by `cardano-cli`.
+- [ADR-013](ADR-013-Metavars-must-follow-screaming-snake-case.md) defines metavar naming conventions that apply to flags defined here.
diff --git a/docs/ADR-013-Metavars-must-follow-screaming-snake-case.md b/docs/ADR-013-Metavars-must-follow-screaming-snake-case.md
@@ -59,3 +59,8 @@ Additionally, screaming snake case is already a _de facto_ standard within `card
 # Conclusion
 
 In this Architecture Decision Record (ADR), we establish the policy of adopting the screaming snake case format for metavariables. We will apply this standard consistently across our codebase to enhance clarity, readability, consistency, and maintainability.
+
+# Related ADRs
+
+- [ADR-006](ADR-006-Using-optparse-applicative-main-repository.md) (rejected) — help text formatting, which displays metavars, is produced using our `optparse-applicative` fork.
+- [ADR-012](ADR-012-standardise-CLI-multiple-choice-flags-construction.md) defines flag construction conventions; flags defined there should use metavar names following this ADR.
diff --git a/docs/ADR-014-Total-conversion-functions-conventions.md b/docs/ADR-014-Total-conversion-functions-conventions.md
@@ -115,4 +115,10 @@ toBaz :: Foo -> Baz
 - It may be a bit less obvious how to discover available conversions, because one would have to browse the type's `Inject` instances to find the conversion functions they are looking for - instead of looking for exported functions.
 
 
+# Related ADRs
+
+- [ADR-009](ADR-009-cardano-api-exports-convention.md) defines module conventions; instance placement ("near the definition of one of the types") should follow those conventions.
+- [ADR-010](ADR-010-cardano-api-script-witness-api.md) — the script witness API converts extensively between `cardano-api` and `cardano-ledger` types; these conversions should use `Inject`/`Convert`.
+- [ADR-015](ADR-015-Cardano-API-WASM-library-for-browser.md) — the `ToJSVal`/`FromJSVal` type class pattern is analogous to the `Inject`/`Convert` pattern defined here.
+
 [modeline]: # ( vim: set spell spelllang=en: )
diff --git a/docs/ADR-015-Cardano-API-WASM-library-for-browser.md b/docs/ADR-015-Cardano-API-WASM-library-for-browser.md
@@ -236,3 +236,8 @@ SOP (or Same-Origin Policy) is a restriction that is enforced by browsers to pro
 Additionally, if SOP was not in place, a very popular but malicious website could easily include a JavaScript snippet that would cause every visitor of the malicious website to silently make potentially costly requests against a victim API, and that would potentially work out as DDOS (Distribute Denegation of Services) attack, by consuming lots of resources from the victim API.
 
 Unfortunately, this means that JavaScript cannot access public API's unless those API's use CORS to lift SOP restrictions. This ADR suggests that there could potentially exist a service like [Koios](https://koios.rest/) that does this, as long as it can be guaranteed that the queries offered by the API are made in a way that is efficient enough, and user supplantation is made impossible or not applicable.
+
+## Related ADRs
+
+- [ADR-004](ADR-004-Support-only-for-mainnet-and-upcoming-eras.md) defines the eras available to the WASM API.
+- [ADR-014](ADR-014-Total-conversion-functions-conventions.md) — the `Inject`/`Convert` pattern is analogous to the `ToJSVal`/`FromJSVal` type classes proposed here.
