V2 migration guide (#717)

Author: csviri

README.md

@@ -8,6 +8,9 @@ by [operator-sdk](https://github.com/operator-framework/operator-sdk).
 
 Our webpage with documentation is getting better every day: https://javaoperatorsdk.io/
 
+**!! NOTE the main branch now contains source code for v2, which is under development, for actual
+version see [v1 branch](https://github.com/java-operator-sdk/java-operator-sdk/tree/v1) !!**
+
 Table of Contents
 ==========
 

docs/_data/sidebar.yml

@@ -13,4 +13,6 @@
     url: /docs/faq
   - title: Contributing
     url: /docs/contributing
+  - title: Migrating from v1 to v2
+    url: /docs/v2-migration
 

docs/documentation/patterns-best-practices.md

@@ -12,10 +12,10 @@ of Java Operator SDK.
 
 ## Implementing a Controller
 
-### Sync of Async Way of Resource Handling
-
 ### Idempotency
 
+### Sync of Async Way of Resource Handling
+
 ## Why to Have Automated Retries?
 
 ## Managing State

docs/documentation/use-samples.md

@@ -58,7 +58,7 @@ The Controller implements the business logic and describes all the classes neede
 
 ```java
 
-@Controller
+@ControllerConfiguration
 public class WebServerController implements Reconciler<WebServer> {
 
     // Return the changed resource, so it gets updated. See javadoc for details.

docs/documentation/v2-migration.md

@@ -0,0 +1,53 @@
+---
+title: Migrating from v1 to v2
+description: Migrating from v1 to v2
+layout: docs
+permalink: /docs/v2-migration
+---
+
+# Migrating from v1 to v2
+
+Version 2 of the framework introduces improvements, features and breaking changes for the APIs both internal and user
+facing ones. The migration should be however trivial in most of the cases. For detailed overview of all major issues
+until the release of
+v`2.0.0` [see milestone on GitHub](https://github.com/java-operator-sdk/java-operator-sdk/milestone/1). For a summary
+and reasoning behind some naming changes
+see [this issue](https://github.com/java-operator-sdk/java-operator-sdk/issues/655)
+
+## User Facing API Changes
+
+The following items are renamed and slightly changed:
+
+- [`ResourceController`](https://github.com/java-operator-sdk/java-operator-sdk/blob/v1/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/ResourceController.java)
+  interface is renamed
+  to [`Reconciler`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Reconciler.java)
+  . In addition, methods:
+    - `createOrUpdate` renamed to `reconcile`
+    - `delete` renamed to `cleanup`
+- Events are removed from
+  the [`Context`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/Context.java)
+  of `Reconciler` methods . The rationale behind this, is that there is a consensus now on the pattern that the events
+  should not be used to implement a reconciliation logic.
+- The `init` method is extracted from `ResourceController` / `Reconciler` to a separate interface
+  called [EventSourceInitializer](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/EventSourceInitializer.java)
+  that `Reconcile` should implement in order to register event sources. See
+  also [sample](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/sample-operators/tomcat-operator/src/main/java/io/javaoperatorsdk/operator/sample/WebappReconciler.java)
+  for usage. Here also
+  the [`EventSourceManager`](https://github.com/java-operator-sdk/java-operator-sdk/blob/v1/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/EventSourceManager.java)
+  is renamed
+  to [`EventSourceRegistry`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSourceRegistry.java)
+  , and it's interface refined.
+- [`@Controller`](https://github.com/java-operator-sdk/java-operator-sdk/blob/v1/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/Controller.java)
+  annotation renamed
+  to [`@ControllerConfiguration`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/api/reconciler/ControllerConfiguration.java)
+
+### Event Sources
+
+- Addressing resources within event sources (and in the framework internally) is now changed from `.metadata.uid` to a
+  pair of `.metadata.name` and optional `.metadata.namespace` of resource. Represented
+  by [`ResourceID.`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/ResourceID.java)
+- The [`Event`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/Event.java)
+  API is simplified. Now if an event source produces an event it needs to just produce an instance of this class.
+- [`EventSource`](https://github.com/java-operator-sdk/java-operator-sdk/blob/main/operator-framework-core/src/main/java/io/javaoperatorsdk/operator/processing/event/source/EventSource.java)
+  is refactored, but the changes are trivial. 
+