docs: add migration guidelines (#860)

asyncapi · Aug 25, 2022 · da9b80b · da9b80b
1 parent 908fde6
commit da9b80b
Show file tree

Hide file tree

Showing 5 changed files with 58 additions and 7 deletions.
diff --git a/docs/README.md b/docs/README.md
@@ -45,14 +45,18 @@ Details which different generator options are supported.
 ### [Presets](./presets.md)
 Goes more in-depth into how the preset system works, which enables full customization of generators.
 
-### [Interpretation of JSON Schema](./interpretation_of_JSON_Schema.md)
+### [Interpretation of JSON Schema](./inputs/JSON_Schema.md)
 Explains how a JSON Schema is interpreted to a data model.
 
+### [Migration](./migration.md)
+As time goes on, major versions are inevitible and expected! You can find the migration guides here.
+
 ### Languages
 Each language has its own limitations, corner cases, and features; thus, each language has separate documentation.
 - [C#](./languages/Csharp.md)
+- [Dart](./languages/Dart.md)
 - [Go](./languages/Go.md)
 - [Java](./languages/Java.md)
 - [JavaScript](./languages/JavaScript.md)
-- [TypeScript](./languages/TypeScript.md)
 - [Rust](./languages/Rust.md)
+- [TypeScript](./languages/TypeScript.md)
diff --git a/docs/interpretation_of_JSON_Schema.md → docs/inputs/JSON_Schema.md b/docs/interpretation_of_JSON_Schema.md → docs/inputs/JSON_Schema.md
diff --git a/docs/migration.md b/docs/migration.md
@@ -0,0 +1,7 @@
+# Migration guides
+
+As Modelina progresses and evolves over time, sometimes it's inevitable that a major version change is required.
+
+When it happens, we try to list the breaking changes and a migration guide, to make transitioning from one major version to another as painless as possible.
+
+- [From v0 to v1](./migrations/version-0-to-1.md)
diff --git a/docs/migrations/version-0-to-1.md b/docs/migrations/version-0-to-1.md
@@ -0,0 +1,40 @@
+# Migration from v0 to v1
+This document contain all the breaking changes and migrations guidelines for adapting your code to the new version.
+
+## Naming conventions have been removed
+In version 0, you where able to control the naming formats for properties and model through the option `namingConvention`. 
+
+This is now removed and replaced with `constraints` which is a mean to simplify the complex task of constraining any type of values to the specifics of an output. Each output has their unique constraints to what is allowed and what is expected as names for properties, models and enums, and enum values.
+
+To read more about the constrain option here:
+- [C#](../constraints/CSharp.md)
+- [Dart](../constraints/Dart.md)
+- [Go](../constraints/Go.md)
+- [Java](../constraints/Java.md)
+- [JavaScript](../constraints/JavaScript.md)
+- [Rust](../constraints/Rust.md)
+- [TypeScript](../constraints/TypeScript.md)
+
+## CommonModel is no more (almost)
+As part of version 1, the previous core model was called `CommonModel` and was a dynamic class which could take the form of any type of model. I.e. one moment it could be defining an object, the next an enum, or multiple at a time. This made it extremely hard to use in the generators, read more about why we decided to change it here: https://github.com/asyncapi/modelina/pull/530
+
+This change means that any time you did some custom presets and interacted with `CommonModel`, you now interact with a variant of the [ConstrainedMetaModel](../internal-model.md#the-constrained-meta-model).
+
+The CommonModel is still being used for the dynamic input processing of JSON Schema.
+
+### Preset hooks
+These are all the preset hook changes:
+- Java, class preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedObjectModel`
+- Java, enum preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedEnumModel`
+- JavaScript, class preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedObjectModel`
+- TypeScript, class preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedObjectModel`
+- TypeScript, Interface preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedObjectModel`
+- TypeScript, enum preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedEnumModel`
+- TypeScript, type preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedMetaModel`
+- Go, struct preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedObjectModel`
+- C#, class preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedObjectModel`
+- C#, enum preset hooks had access to `model: CommonModel` which has now been changed to `model: ConstrainedEnumModel`
+
+General changes:
+- Hooks that gave access to properties/fields formally had the arguments `property`, `propertyName` and `type`, these are now wrapped within the [`ConstrainedObjectPropertyModel`](./internal-model.md#the-constrained-meta-model) and can be accessed through the `property` argument.
+- Hooks that gave access to enum items, now has the type [`ConstrainedEnumValueModel`](./internal-model.md#the-constrained-meta-model).
diff --git a/docs/usage.md b/docs/usage.md
@@ -43,7 +43,7 @@ There are two ways to generate models for an AsyncAPI document.
 
 The library expects the `asyncapi` property for the document to be set in order to understand the input format.
 
-The message payloads, since it is a JSON Schema variant, is [interpreted as a such](./interpretation_of_JSON_Schema.md).
+The message payloads, since it is a JSON Schema variant, is [interpreted as a such](./inputs/JSON_Schema.md).
 
 ## Generate models from JSON Schema documents
 
@@ -53,7 +53,7 @@ There is one way to generate models for a JSON Schema document.
 
 We support both draft-4, draft-6, and draft-7 documents.
 
-The library expects the `$schema` property for the document to be set in order to understand the input format. By default, if no other inputs are detected, it defaults to `JSON Schema draft 7`. The process of interpreting a JSON Schema to a model can be read [here](./interpretation_of_JSON_Schema.md).
+The library expects the `$schema` property for the document to be set in order to understand the input format. By default, if no other inputs are detected, it defaults to `JSON Schema draft 7`. The process of interpreting a JSON Schema to a model can be read [here](./inputs/JSON_Schema.md).
 
 ## Generate models from Swagger 2.0 documents
 
@@ -63,7 +63,7 @@ There are one way to generate models from a Swagger 2.0 document
 
 The Swagger input processor expects that the property `swagger` is defined in order to know it should be processed.
 
-The response payload and `body` parameters, since it is a JSON Schema variant, is [interpreted as a such](./interpretation_of_JSON_Schema.md).
+The response payload and `body` parameters, since it is a JSON Schema variant, is [interpreted as a such](./inputs/JSON_Schema.md).
 
 ## Generate models from OpenAPI documents
 
@@ -73,7 +73,7 @@ There are one way to generate models from an OpenAPI document
 
 The OpenAPI input processor expects that the property `openapi` is defined in order to know it should be processed.
 
-The response and request payloads, since it is a JSON Schema variant, is [interpreted as a such](./interpretation_of_JSON_Schema.md).
+The response and request payloads, since it is a JSON Schema variant, is [interpreted as a such](./inputs/JSON_Schema.md).
 
 ## Generate models from TypeScript type files
 
@@ -96,7 +96,7 @@ There are one way to generate models from an OpenAPI document
 
 The OpenAPI input processor expects that the property `openapi` is defined in order to know it should be processed.
 
-The response and request payloads, since it is a JSON Schema variant, is [interpreted as a such](./interpretation_of_JSON_Schema.md).
+The response and request payloads, since it is a JSON Schema variant, is [interpreted as a such](./inputs/JSON_Schema.md).
 
 ## Generate Go models