docs: decision record about transformers versioning scheme (#4634)

* docs: decision record about transformers versioning scheme * Update docs/developer/decision-records/2024-11-19-transformer-version-scheme/README.md Co-authored-by: Paul Latzelsperger <[email protected]> * Update docs/developer/decision-records/2024-11-19-transformer-version-scheme/README.md Co-authored-by: Paul Latzelsperger <[email protected]> --------- Co-authored-by: Paul Latzelsperger <[email protected]>
eclipse-edc · Nov 20, 2024 · 4819c8e · 4819c8e
1 parent 08f913e
commit 4819c8e
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 0 deletions.
diff --git a/docs/developer/decision-records/2024-11-19-transformer-version-scheme/README.md b/docs/developer/decision-records/2024-11-19-transformer-version-scheme/README.md
@@ -0,0 +1,35 @@
+# Transformers versioning scheme
+
+## Decision
+
+We will remove the thrown exception when calling `TypeTransformerRegistry#forContext` on nested TypeTransformerRegistry
+for supporting incremental versioning scheme.
+
+## Rationale
+
+The current approach for versioning is to create a new `TypeTransformerRegistry` instance for each context + version.
+e.g. in dsp context:
+
+```java
+var dspApiTransformerRegistryV08 = transformerRegistry.forContext("dsp-api:v0.8");
+var dspApiTransformerRegistryV2024_1 = transformerRegistry.forContext("dsp-api:2024/1");
+```
+
+This versioning scheme is well suited for the dsp context where message serialization/deserialization may have substantial changes
+between versions and where versions don't have a direct relationship between them.
+
+This approach might not be the best for the management-api context for example, where we usually apply incremental
+changes in the form of alpha APIs introducing new fields or changing the shape of existing fields in limited entities,
+while preserving the existing fields and their shape in others.
+
+## Approach
+
+By removing the exception when calling `TypeTransformerRegistry#forContext` on a nested context, it will be possible to
+create specific versioned context containing only the overridden transformers.
+
+```java
+var mgmtContext = transformerRegistry.forContext("management-api");
+var mgmtContextV4Alpha = mgmtContext.forContext("V4Alpha");
+// override mgmtContext transformer
+mgmtContextV4Alpha.registerTransformer();
+```
diff --git a/docs/developer/decision-records/README.md b/docs/developer/decision-records/README.md
@@ -67,4 +67,5 @@
 - [2024-10-10 DAPS module deprecation](./2024-10-10-daps-deprecation)
 - [2024-10-24 bidirectional-data-transfers](./2024-10-24-bidirectional-data-transfers)
 - [2024-11-06 configuration-injection](./2024-11-06-configuration-injection)
+- [2024-11-19 transformer-version-scheme](./2024-11-19-transformer-version-scheme)