Merge pull request #791 from finos/release/v3.0

Update reference doc for BDK release 3.0
finos · Feb 7, 2024 · 2fc51fb · 2fc51fb
2 parents 9048466 + 1dc3078
commit 2fc51fb
Show file tree

Hide file tree

Showing 4 changed files with 146 additions and 11 deletions.
diff --git a/.github/workflows/build.yml b/.github/workflows/build.yml
@@ -22,6 +22,6 @@ jobs:
         java-version: '17'
 
     - name: Build with Gradle
-      uses: gradle/gradle-build-action@v2
+      uses: gradle/gradle-build-action@v2.4.2
       with:
         arguments: build jacocoTestReport jacocoTestCoverageVerification
diff --git a/docs/_config.yml b/docs/_config.yml
@@ -1,10 +1,10 @@
-title: BDK 2.0 for Java
+title: BDK 3.0 for Java
 description: Reference documentation for using the Symphony BDK to build bots
 theme: just-the-docs
 plugins:
   - jemoji
 url: https://symphony-bdk-java.finos.org
 color_scheme: symphony
 aux_links:
-  "BDK 2.0 on GitHub":
+  "BDK 3.0 on GitHub":
     - "//github.com/finos/symphony-bdk-java"
diff --git a/docs/index.md b/docs/index.md
@@ -6,6 +6,18 @@ nav_order: 1
 
 # Symphony BDK Reference Documentation
 
+> [!NOTE]
+> BDK version 3.0: Major change !
+> 
+> The newly introduced BDK version 3.0 relies on Java 17 and SpringBoot 3. This is a major change that allows Symphony to continue to propose the latest security fixes following the end of support of Spring Boot 2 and also to keep up with the latest evolutions of Java.
+> 
+> For the next 6 months Symphony will provide critical security fixes for BDK 2.0 where possible (since Spring gives no guarantees for their packages).
+> 
+> Please consider migrating your Bots in the coming months to benefit from the latest features and support. 
+
+> [!IMPORTANT]
+> As detailed above, the BDK version 2.0 will stop being supported by Symphony on August 15.
+
 This reference guide provides detailed information about the Symphony BDK. It provides a comprehensive documentation
 for all features and abstractions made on top of the [Symphony REST API](https://developers.symphony.com/restapi/reference/introduction).
 

diff --git a/docs/migration.md b/docs/migration.md
@@ -4,6 +4,129 @@ title: Migration Guide
 nav_order: 3
 ---
 
+# Migration guide to Symphony BDK 3.0 from 2.0
+
+This guide provides information about how to migrate from Symphony BDK 2.0 to BDK 3.0. Migration for the following topics will be detailed here:
+- JDK17
+- Dependencies
+
+## JDK17
+The major change in BDK 3.0 is the migration from JDK8 to JDK17, this migration requires 
+- IDE update
+- Package naming change
+- New compiler argument in build tool
+
+### IDE update
+BDK Bot developers needs install JDK17 in their development environment, and configure IDE to used JDK17 instead of JDK8.
+
+
+### Package naming change
+Replace all `javax.xxx` package imports to `jakarta.xxx`.
+
+Java BDK 2.0
+
+```java
+    import javax.ws.rs.ProcessingException;
+```
+Java BDK 3.0
+
+```java
+    import jakarta.ws.rs.ProcessingException;
+```
+
+### New compiler argument in build tool
+
+A new `-parameters` argument must be passed to the compiler, so that `@Slash` commands and/or other java annotations continue to work
+with JDK17.
+
+#### Maven
+
+```xml
+    <plugin>
+        <groupId>org.apache.maven.plugins</groupId>
+        <artifactId>maven-compiler-plugin</artifactId>
+        <version>${maven.compiler.version}</version>
+        <configuration>
+            <compilerArgs>
+                <arg>-parameters</arg>
+            </compilerArgs>
+        </configuration>
+    </plugin>
+```
+
+#### Gradle
+```groovy
+    tasks.withType(JavaCompile) {
+        options.encoding = 'UTF-8'
+        options.compilerArgs << '-parameters'
+    }
+```
+
+## Dependencies
+
+Simply update BDK dependency version to `3.0.0`
+
+### Spring Boot based project
+
+```xml
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>org.finos.symphony.bdk</groupId>
+            <artifactId>symphony-bdk-bom</artifactId>
+            <version>3.0.0</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+
+<dependencies>
+    <dependency>
+        <groupId>org.finos.symphony.bdk</groupId>
+        <artifactId>symphony-bdk-core-spring-boot-starter</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter</artifactId>
+    </dependency>
+</dependencies>
+```
+
+### Non framework based project
+
+#### Java BDK 3.0
+```xml
+<dependencyManagement>
+    <dependencies>
+        <dependency>
+            <groupId>org.finos.symphony.bdk</groupId>
+            <artifactId>symphony-bdk-bom</artifactId>
+            <version>3.0.0</version>
+            <type>pom</type>
+            <scope>import</scope>
+        </dependency>
+    </dependencies>
+</dependencyManagement>
+
+<dependencies>
+    <dependency>
+        <groupId>org.finos.symphony.bdk</groupId>
+        <artifactId>symphony-bdk-core</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.finos.symphony.bdk</groupId>
+        <artifactId>symphony-bdk-http-jersey2</artifactId> <!-- or symphony-bdk-http-webclient -->
+        <scope>runtime</scope>
+    </dependency>
+    <dependency>
+        <groupId>org.finos.symphony.bdk</groupId>
+        <artifactId>symphony-bdk-template-freemarker</artifactId>  <!-- or symphony-bdk-http-handlebars -->
+        <scope>runtime</scope>
+    </dependency>
+</dependencies>
+```
+
 # Migration guide to Symphony BDK 2.0
 
 This guide provides information about how to migrate from Symphony SDK 1.0 to BDK 2.0. Migration for the following topics will be detailed here:
@@ -51,14 +174,14 @@ If your project is not framework based, dependencies such as *jersey* and *freem
 </dependencyManagement>
 
 <dependencies>
-<dependency>
-    <groupId>org.finos.symphony.bdk</groupId>
-    <artifactId>symphony-bdk-core-spring-boot-starter</artifactId>
-</dependency>
-<dependency>
-    <groupId>org.springframework.boot</groupId>
-    <artifactId>spring-boot-starter</artifactId>
-</dependency>
+    <dependency>
+        <groupId>org.finos.symphony.bdk</groupId>
+        <artifactId>symphony-bdk-core-spring-boot-starter</artifactId>
+    </dependency>
+    <dependency>
+        <groupId>org.springframework.boot</groupId>
+        <artifactId>spring-boot-starter</artifactId>
+    </dependency>
 </dependencies>
 ```