CRD-Generator v2 migration notes (6702)

Add initial migration guide for CRD-Generator v2
---
Add notes about API compatibiliy, new tooling and started with new annotations
---
Add more notes
---
Add more notes
---
Add notes about default values and annotated types
---
Reordered notes and separate breaking changes
---
Revert removal of CLI notice

crd-generator/apt/README.md

@@ -1,6 +1,8 @@
 # CRD Generator Annotation Processor
 _Deprecated since 7.0.0_
 
+Please follow our [CRD Generator v2 Migration Guide](../../doc/CRD-generator-migration-v2.md) to replace it.
+
 ## Usage
 
 with Maven:

doc/CRD-generator-migration-v2.md

@@ -0,0 +1,107 @@
+# Migration from CRD Generator v1 to CRD Generator v2
+
+## Overview
+
+### CRD Generator v1
+
+_Deprecated since 7.0.0_
+
+- **CRD Generator API v1** - `io.fabric8:crd-generator-api`  
+  _Core implementation of the old generator, based on [sundrio](https://github.com/sundrio/sundrio)._
+- **CRD Generator annotation processing tool (APT)** - `io.fabric8:crd-generator-apt`  
+  _Annotation processor which hooks into the build process to generate CRDs._
+
+### CRD Generator v2
+
+_GA since 7.0.0_
+
+- **CRD Generator API v2** - `io.fabric8:crd-generator-api-v2`  
+  _Core implementation of the new generator, based on [Jackson/jsonSchema](https://github.com/FasterXML/jackson-module-jsonSchema)._
+- **CRD Generator Collector** - `io.fabric8:crd-generator-collector`  
+  _Shared component to find and load compiled Custom Resource classes in directories and Jar files._
+- **CRD Generator Maven Plugin** - `io.fabric8:crd-generator-maven-plugin`   
+  _Maven plugin that generates CRDs during the build process._
+- **CRD Generator CLI** - `io.fabric8:crd-generator-cli`    
+  _CLI tool that generates CRDs when executed._
+
+## API Compatibility
+
+CRD Generator v1 and v2 are using **the same set of annotations**.  
+This means you can keep your code as is and replace just the CRD Generator
+annotation processor with your [tool of choice](#new-tooling).
+
+The API itself is not compatible but very similar.
+
+## Breaking Changes
+
+### New restrictions on annotations
+
+With CRD Generator v2 the following annotations are restricted to certain field types:
+
+- `@Min` and `@Max` are restricted to numeric fields
+- `@Pattern` is restricted to string fields
+
+### Migrating from v6
+
+In case you are migrating directly from fabric8/kubernetes-client v6, the following change affects you:
+
+The type of `format` in `@PrinterColumn` has changed from string to enum `PrinterColumnFormat`.
+
+## New Tooling
+
+To replace the [CRD Generator annotation processor](../crd-generator/apt/README.md) you can use the following tools:
+
+- [CRD Generator Maven Plugin](../crd-generator/maven-plugin/README.md)
+- [CRD Generator CLI tool](../crd-generator/cli/README.md)
+
+The tools use the same base, which means they should generate the same CRDs if similar configuration
+parameter are used. One of the enhancements of the new tooling is that they can be configured easily.
+Please read the README of the tool for details on usage and configuration.
+
+## New annotations
+
+Several new annotations have been introduced since 7.0.0. They will be used by the **CRD Generator v2 implementation only**
+since CRD Generator v1 won't get new features from now on.
+
+- `@Categories`
+- `@AdditionalPrinterColumn`
+- `@SelectableField`
+- `@AdditionalSelectableField`
+- `@Size`
+
+Read the Javadoc of the annotations and the [CRD Generator documentation](CRD-generator.md) to get details.
+
+## `@Min` / `@Max` inclusiveness
+
+The `@Min` and `@Max` annotations have been extended with a second argument to define the inclusiveness.
+By default, the value in the annotation is meant to be inclusive like before.
+
+## Annotated Types
+
+`@Pattern`, `@Min`, `@Max` will be detected if they are used to annotate the type of a List or a Map.
+
+Example:
+```java
+List<@Pattern("(a|b)") String> myList;
+Map<String, @Pattern("(a|b)") String> myMap;
+```
+Result:
+```yaml
+myList:
+  items:
+    pattern: "(a|b)+"
+    type: "string"
+  type: "array"
+myMap:
+  additionalProperties:
+    pattern: "(a|b)+"
+    type: "string"
+  type: "object"
+```
+
+## Default values for CRD fields can be numeric or boolean
+
+Previously default values defined by `@Default` could only be used on string fields. 
+With CRD Generator v2 defaults can be set on numeric and boolean fields, too.
+In the same way is `@JsonProperty(defaultValue)` now working.
+

doc/CRD-generator.md

@@ -4,6 +4,8 @@ The [CRD Generator annotation processing tool (APT)](../crd-generator/apt/README
 
 As a replacement, we're currently providing a new version of the API in `io.fabric8:crd-generator-api-v2` and a few tools to be able to leverage it in your projects.
 
+A migration guide can be found [here](CRD-generator-migration-v2.md). 
+
 The following list contains the available tooling:
 - [CRD Generator Maven Plugin](../crd-generator/maven-plugin/README.md): A Maven plugin that generates CRDs during the build process.
 - [CRD Generator CLI tool](../crd-generator/cli/README.md): A CLI tool that generates CRDs when executed.

doc/MIGRATION-v7.md

@@ -331,6 +331,6 @@ We are no longer supporting it.
 ### CRD Generator annotation processor deprecated <a href="#crd-generator-annotation-processor-deprecated" id="crd-generator-annotation-processor-deprecated"/>
 
 The CRD Generator annotation processing tool (APT) (`io.fabric8:crd-generator-apt`) and its API (`io.fabric8:crd-generator-api`) are being deprecated and will eventually be removed once we offer a complete replacement for all users.
-The CRD Generator API users should use the v2 version of the API ((`io.fabric8:crd-generator-api-v2`) instead. 
+The CRD Generator API users should use the v2 version of the API (`io.fabric8:crd-generator-api-v2`) instead. 
 
 You can find out more about its replacement in the [CRD Generator documentation](./CRD-generator.md)