From 4819c8ec3036654391e4b2f81b414667797e3e48 Mon Sep 17 00:00:00 2001 From: Enrico Risa Date: Wed, 20 Nov 2024 16:30:49 +0100 Subject: [PATCH] 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 <43503240+paullatzelsperger@users.noreply.github.com> * Update docs/developer/decision-records/2024-11-19-transformer-version-scheme/README.md Co-authored-by: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> --------- Co-authored-by: Paul Latzelsperger <43503240+paullatzelsperger@users.noreply.github.com> --- .../README.md | 35 +++++++++++++++++++ docs/developer/decision-records/README.md | 1 + 2 files changed, 36 insertions(+) create mode 100644 docs/developer/decision-records/2024-11-19-transformer-version-scheme/README.md 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 new file mode 100644 index 0000000000..feab31809f --- /dev/null +++ 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(); +``` \ No newline at end of file diff --git a/docs/developer/decision-records/README.md b/docs/developer/decision-records/README.md index 3338f418e9..bf702e9a92 100644 --- 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)