Link related ADRs to each other

.github/mlc_config.json

@@ -8,6 +8,24 @@
         },
         {
             "pattern": "https://iohk.zendesk.com"
+        },
+        {
+            "pattern": "^https://www.npmjs.com"
+        },
+        {
+            "pattern": "^https://stackoverflow.com"
+        },
+        {
+            "pattern": "^https://hub.docker.com"
+        },
+        {
+            "pattern": "^https://nixos.wiki"
+        },
+        {
+            "pattern": "^https://www.freedesktop.org"
+        },
+        {
+            "pattern": "scripts/byron-to-alonzo/mkfiles.sh"
         }
     ],
     "retryOn429": true,

.github/workflows/markdown-links-ci-check.yml

@@ -8,8 +8,8 @@ jobs:
   markdown-link-check:
     runs-on: ubuntu-latest
     steps:
-    - uses: actions/checkout@v3
-    - uses: gaurav-nelson/github-action-markdown-link-check@v1
+    - uses: actions/checkout@v4
+    - uses: tcort/github-action-markdown-link-check@v1
       with:
         use-quiet-mode: yes
         config-file: '.github/mlc_config.json'

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 fork 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.

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.
+
 

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.

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.

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.

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`.
+

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.

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.
+

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`.

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.

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.

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.

docs/ADR-014-Total-conversion-functions-conventions.md

@@ -20,7 +20,7 @@ Some conversion functions with lengthy names, are not very convenient to use.
 
 ## Type classes
 
-For total functions, which are simply converting a value from one type to another, we can use type classes [`Inject` (from `cardano-ledger`)](https://cardano-ledger.cardano.intersectmbo.org/cardano-ledger-core/Cardano-Ledger-BaseTypes.html#t:Inject) & [`Convert`](https://cardano-api.cardano.intersectmbo.org/cardano-api/Cardano-Api-Internal-Eras.html#t:Convert):
+For total functions, which are simply converting a value from one type to another, we can use type classes [`Inject` (from `cardano-ledger`)](https://cardano-ledger.cardano.intersectmbo.org/cardano-ledger-core/Cardano-Ledger-BaseTypes.html#t:Inject) & [`Convert`](https://cardano-api.cardano.intersectmbo.org/cardano-api/Cardano-Api-Era.html#t:Convert):
 ```haskell
 class Inject t s where
   inject :: t -> s
@@ -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: )

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.

docs/Debugging-cardano-cli-errors-on-a-testnet.md

@@ -2,7 +2,7 @@
 
 This document is intended for Cardano node and `cardano-cli` (CLI) users, as well as Cardano developers that wish to investigate CLI problems.
 
-We recommend making sure the `cardano-node` tests pass before starting to debug a problem. Additionally, take a look at the [Consensus sanity checklist](https://ouroboros-consensus.cardano.intersectmbo.org/docs/for-developers/SanityChecks).
+We recommend making sure the `cardano-node` tests pass before starting to debug a problem. Additionally, take a look at the [Consensus sanity checklist](https://ouroboros-consensus.cardano.intersectmbo.org/docs/howtos/contributing/sanity_checks).
 
 Once the node tests successfully pass, and you've read through the Consensus checklist, collect node logs to speed up the process of finding the cause of a problem. Below, we describe the steps to run a node that connects to a given testnet and get access to a `cardano-cli` that can be used to communicate with the node. These instructions work on a Unix environment with `nix` installed.
 

docs/getting-started/cli.md

@@ -1,7 +1,7 @@
 # Command Line Interface
 
 In previous tutorials, we have always worked with command `cardano-node`,
-but when we built the software from source as described [here](install.md),
+but when we built the software from source as described [here](https://developers.cardano.org/docs/get-started/infrastructure/node/installing-cardano-node/),
 we actually installed other executables as well, including the command line interface `cardano-cli`.
 
 This command line interface provides a collection of tools for key generation, transaction construction, certificate creation

docs/getting-started/running-chairman-tests.md

@@ -19,7 +19,7 @@ and various run-modes:
 You must already be able to build everything in the `cardano-node` repository
 using `cabal` (not `nix`).
 
-See [Installing a node from source](install.md).
+See [Installing a node from source](https://developers.cardano.org/docs/get-started/infrastructure/node/installing-cardano-node/).
 
 ## Running the chairman test
 The chairman test will run some testnets and perform some basic tests to ensure they

docs/logging-monitoring/ekg.md

@@ -1,6 +1,6 @@
 # Monitoring a Node with EKG
 
-This tutorial assumes that you have installed `cardano-node` as explained [here](../getting-started/install.md).
+This tutorial assumes that you have installed `cardano-node` as explained [here](https://developers.cardano.org/docs/get-started/infrastructure/node/installing-cardano-node/).
 
 1. For security reasons, EKG can normally only be used to monitor a node
    running on the local machine.

docs/reference/byron-genesis.md

@@ -146,7 +146,7 @@ The key `protocolMagic` defines the protocol magic number. When the protocol mag
 The `protocolMagic` value can either be an object with the two fields described above, or just a plain integer. In the latter case, `requiresNetworkMagic` will take the default value of `RequiresMagic`.
 
 Relevant:
-- [cardano-ledger - Genesis test](https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/ledger/impl/test/Test/Cardano/Chain/Genesis/Json.hs#L69)
+- [cardano-ledger - Genesis test](https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/ledger/impl/testlib/Test/Cardano/Chain/Genesis/Json.hs)
 - [cardano-ledger - ProtocolMagic](https://github.com/intersectmbo/cardano-ledger/blob/master/eras/byron/crypto/src/Cardano/Crypto/ProtocolMagic.hs)
 
 ## heavyDelegation

docs/reference/configuring-a-node-using-yaml.md

@@ -65,4 +65,4 @@ The genesis file is very important, as it sets four key parameters:
 * `MaxLovelaceSupply`: the total amount of lovelaces in the blockchain.
 * `startTime`: the time of slot zero.
 
-For details on using the command line interface, stopping and starting the node, and ensuring the node is connected to the Cardano network, please refer to the [README file](https://github.com/intersectmbo/cardano-node/blob/master/README.rst).
+For details on using the command line interface, stopping and starting the node, and ensuring the node is connected to the Cardano network, please refer to the [README file](https://github.com/intersectmbo/cardano-node/blob/master/README.md).

docs/reference/create-cardano.md

@@ -170,7 +170,7 @@ Starting the cluster requires topology files for each of the nodes. For example:
    ]
  }
 ```
-Note: For details about topology files please refer to [Understanding configuration files](../getting-started/understanding-config-files.md).
+Note: For details about topology files please refer to [Understanding configuration files](configuring-a-node-using-yaml.md).
 
 
 Then, run the nodes with block production keys, for example:

docs/reference/plutus/plutus-minting-script-example.md

@@ -34,7 +34,7 @@ This will output `anyone-can-mint.plutus` in the `generated-plutus-scripts` dir.
 
 #### Setting up a local Alonzo node cluster
 
-First follow the [install doc](https://github.com/input-output-hk/cardano-node-wiki/blob/main/docs/getting-started/install.md) if you haven't. This convenient script will set up an Alonzo cluster immediately on your local machine:
+First follow the [install doc](https://developers.cardano.org/docs/get-started/infrastructure/node/installing-cardano-node/) if you haven't. This convenient script will set up an Alonzo cluster immediately on your local machine:
 
 ```bash
 ./scripts/byron-to-alonzo/mkfiles.sh alonzo

docs/stake-pool-operations/0_core_relay.md

@@ -48,4 +48,4 @@ Make your __relay node__ `talk` to your __block-producing__ node and __other rel
 **Note**: If you want to connect to IPv4 and IPv6 relays, you must either not specify host addresses when starting `cardano-node` or make sure to specify
 both an IPv4 and IPv6 host address.
 
-Please see [Understanding configuration files](../getting-started/understanding-config-files.md) to learn about P2P topology.
+Please see [Understanding configuration files](../reference/configuring-a-node-using-yaml.md) to learn about P2P topology.