Total conversion functions conventions

Author: carbolymer

docs/ADR-008-Use-RIO-in-cardano‐cli.md

@@ -1,6 +1,5 @@
 # Status
-- [x] Adopted 2025/02/10
-
+- [x] Adopted 2025-02-10
 
 # Required Reading
 
@@ -183,4 +182,4 @@ The purpose of `CustomCliException` is to represent explicitly thrown, structure
 # Consequences
 - 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`
+- 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`

docs/ADR-009-cardano-api-exports-convention.md

@@ -1,6 +1,6 @@
 # Status
 
-✅ Accepted 21-02-2025
+✅ Accepted 2025-02-21
 
 # Context
 

docs/ADR-010-cardano-api-script-witness-api.md

@@ -1,6 +1,6 @@
 # Status
 
--[x] Accepted 13-03-2025
+-[x] Accepted 2025-03-13
 
 # Context
 

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

@@ -0,0 +1,70 @@
+# Status
+
+- [ ] Proposed 2024-05-07
+
+# Context
+
+## The Problem
+In `cardano-api` we have multiple functions performing conversions between one value of the type to the other, for example:
+
+```haskell
+toShelleyScriptHash :: ScriptHash -> ScriptHash
+fromShelleyScriptHash :: ScriptHash -> ScriptHash
+```
+
+There are multiple naming conventions for the conversion functions which makes them hard to locate.
+Some conversion functions with lengthy names, are not very convenient to use.
+
+## Solution Proposal
+
+### Type classes
+
+For total functions, which are simply converting a value from one type to another, we can use type classes [`Inject`](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):
+```haskell
+class Inject t s where
+  inject :: t -> s
+
+class Convert (f :: a -> Type) (g :: a -> Type) where
+  convert :: forall a. f a -> g a
+```
+
+The use of those conversion functions is limited to **internal use only**.
+The library should still export conversion functions with explicit type names for better readability.
+
+### Explicit conversion functions
+
+For explicit conversion functions, the following naming convention should follow:
+
+```haskell
+fooToBar :: Foo -> Bar
+```
+
+
+If the module exporting conversion functions is meant to be imported qualified, and provides functions for operating on a single data type, a shorter name with `from` prefix is allowed:
+
+```haskell
+module Data.Foo where
+
+fromBar :: Bar -> Foo
+```
+
+where the usage would look like:
+```haskell
+import Data.Foo qualified as Foo
+
+Foo.fromBar bar
+```
+
+# Decision
+
+TBD
+
+# Consequences
+
+## Advantages
+- An uniform API for total conversions
+- Less exported symbols, which currently have few conventions for the conversions
+- Less maintenance burden with regards to the naming conventions of the conversion functions
+
+## Disadvantages
+- It may be a bit difficult 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.