Use Spoteless for header checking and code-formatting

.github/workflows/maven-verify.yml

@@ -2,35 +2,45 @@ name: sdk-java Verify
 
 on:
   push:
-    branches:
-      - main
+    branches: [ main ]
   pull_request:
-    branches:
-      - main
+    branches: [ main ]
 
 jobs:
-  build:
+  lint:
+    name: Lint (Spotless + Checkstyle)
     runs-on: ubuntu-latest
+    steps:
+      - name: Checkout sdk-java
+        uses: actions/checkout@v4
+
+      - name: Set up JDK 17
+        uses: actions/setup-java@v4
+        with:
+          distribution: temurin
+          java-version: 17
+          cache: maven
+
+      - name: Spotless + Checkstyle (fail fast)
+        run: mvn -B -DskipTests spotless:check checkstyle:check
 
+  build:
+    name: Build & Verify
+    needs: lint
+    runs-on: ubuntu-latest
     steps:
-      # 1. Checkout this repo
       - name: Checkout sdk-java
         uses: actions/checkout@v4
 
-      # 2. Set up JDK 17 for both builds
       - name: Set up JDK 17
         uses: actions/setup-java@v4
         with:
           distribution: temurin
           java-version: 17
-          cache: 'maven'
+          cache: maven
 
-      # 3. Verify the main sdk-java project, excluding the two agentic modules
-      - name: Verify with Maven
+      - name: Verify with Maven (core)
         run: |
-          mvn -B -f pom.xml clean install verify -am
+          mvn -B -f pom.xml clean verify
 
-      # 4. Verify examples
-      - name: Verify Examples with Maven
-        run: |
-          mvn -B -f examples/pom.xml clean install verify
+      # TODO: run examples once we fix the close issue

CONTRIBUTING.md

@@ -1,5 +1,134 @@
-## Hacking on Serverless Workflow Java SDK in Gitpod
+# Contributing
 
-If you have a web browser, you can get a fully pre-configured development environment in one click:
+Thanks for helping improve this project! This guide explains the local dev setup, the formatting/licensing workflow, testing, and how to propose changes.
 
-[![Open in Gitpod](https://gitpod.io/button/open-in-gitpod.svg)](https://gitpod.io/#https://github.com/serverlessworkflow/sdk-java)
+---
+
+## TL;DR (Fast path)
+
+1. **Install prerequisites:** JDK 17+, Maven 3.8+, Git.
+2. **Clone** the repo and create a branch: `git checkout -b my-fix`.
+3. **Build locally:** run `mvn clean install` from the repo root. Spotless will **apply formatting and license headers** during the build.
+4. **Before pushing:** run `mvn -DskipTests spotless:check checkstyle:check`.
+5. **Open a PR** with a clear title and description.
+
+---
+
+## Project Conventions
+
+### Java, Maven, and modules
+
+* This is a **multi-module Maven** project.
+* **Java 17** is the baseline.
+* Build with `mvn -B verify` (CI runs with `-DskipTests` selectively when needed).
+
+### Formatting and License Headers
+
+We use **Spotless** (Maven) to:
+
+* Format Java with **google-java-format**.
+* Insert/normalize **license headers** (the header content is defined **inline** in the parent POM’s `<licenseHeader>` configuration).
+
+> **Do not** hand-format files or hand-edit headers; let Spotless do it. Running `mvn clean install` locally will mutate sources to match the standard.
+
+### Checkstyle
+
+We keep **Checkstyle** to enforce additional rules. CI fails if formatting or style checks fail.
+
+---
+
+## Developer Setup
+
+### Prerequisites
+
+* **JDK 17+**
+* **Maven 3.8+**
+* **Git**
+* Optional IDE plugins:
+
+  * IntelliJ: *Google Java Format* plugin (for local editing experience). Spotless remains the source of truth.
+
+### Local build & formatting
+
+* Run `mvn clean install` from the repo root. During the build, Spotless **applies** formatting and license headers.
+* Before pushing, run `mvn -DskipTests spotless:check checkstyle:check` to ensure CI will pass.
+
+---
+
+## Testing
+
+* **Unit tests:** `mvn -q test` or `mvn verify`.
+* **Integration tests (if defined):** Use the dedicated Maven profile exposed by the module, e.g. `-Pintegration-tests`.
+* Prefer fast, deterministic tests. Avoid time-sensitive sleeps; use time abstractions or awaitility-style utilities.
+
+### Test Guidelines
+
+* Use clear, behavior-driven names: `methodName_shouldDoX_whenY`.
+* Keep one logical assertion per test (or one behavior per test).
+* Mock only external dependencies; don’t over-mock domain logic.
+* Make tests independent; no ordering assumptions.
+
+---
+
+## Commit & PR Guidelines
+
+### Branching
+
+* Use short, descriptive names: `fix/formatter`, `feat/http-call`, `docs/contributing`.
+
+### Commit messages
+
+* Keep messages clear and imperative: `Fix header resolution for child modules`.
+* Conventional Commits are welcome (`feat:`, `fix:`, `docs:`, `test:`, `refactor:`). Example: `feat: add A2A call task support`.
+
+### Pull Requests
+
+* Describe the **problem**, the **solution**, and any **trade-offs**.
+* Include before/after snippets or screenshots when relevant.
+* Link related issues.
+* Check the box:
+
+  * [ ] `mvn -DskipTests spotless:check checkstyle:check` passes locally
+  * [ ] Unit/integration tests updated
+  * [ ] Public API changes documented/Javadoc updated
+  * [ ] No unrelated formatting churn (Spotless should keep this minimal)
+
+---
+
+## Code Style & Design Notes
+
+* **Immutability first:** prefer `final` fields and defensive copies.
+* **Null-safety:** use `Objects.requireNonNull` at boundaries; consider `Optional` for truly optional returns (don’t use it for fields/params).
+* **Exceptions:** throw specific exceptions; include actionable messages; don’t swallow errors.
+* **Logging:** use SLF4J; no `System.out.println`; keep logs structured and at appropriate levels.
+* **APIs:** document with Javadoc; avoid breaking changes to public APIs unless necessary and called out in release notes.
+* **Generics & type-safety:** prefer precise types over `Object`; isolate unchecked casts.
+* **Performance:** avoid premature optimization; measure first; add micro-benchmarks (JMH) when optimizing hot paths.
+
+---
+
+## License Headers
+
+* The license header is defined **inline** in the parent POM under Spotless’ `<licenseHeader>`.
+* To update it, edit the parent POM and run `mvn spotless:apply` to propagate changes.
+
+---
+
+## CI
+
+* CI runs `spotless:check` and `checkstyle:check` to ensure consistent formatting and style.
+* Builds fail if formatting or headers drift. Run `mvn spotless:apply` locally to fix.
+
+---
+
+## Troubleshooting
+
+* **Spotless changed files during build?** That’s expected locally. Review `git status`, then stage and commit the updates.
+* **CI red on formatting?** Run `mvn spotless:apply` locally, commit, and push.
+* **Running only a submodule?** Prefer `mvn -pl <module> -am …` from the repo root so parent config (Spotless/Checkstyle) is applied consistently.
+
+---
+
+## Questions
+
+Open a discussion or issue on the repository. Thanks for contributing! 🎉

examples/events/pom.xml

@@ -8,6 +8,12 @@
     </parent>
     <name>Serverless Workflow :: Examples :: Events</name>
     <artifactId>serverlessworkflow-examples-events</artifactId>
+
+    <properties>
+        <mainClass>events.EventExample</mainClass>
+    </properties>
+
+
     <dependencies>
         <dependency>
             <groupId>io.serverlessworkflow</groupId>
@@ -18,4 +24,12 @@
             <artifactId>slf4j-simple</artifactId>
         </dependency>
     </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+            </plugin>
+        </plugins>
+    </build>
 </project>

examples/simpleGet/pom.xml

@@ -8,6 +8,11 @@
     </parent>
     <artifactId>serverlessworkflow-examples-simpleGet</artifactId>
     <name>Serverless Workflow :: Examples :: SimpleGet</name>
+
+    <properties>
+        <mainClass>io.serverlessworkflow.impl.BlockingExample</mainClass>
+    </properties>
+
     <dependencies>
         <dependency>
             <groupId>io.serverlessworkflow</groupId>
@@ -30,4 +35,15 @@
             <artifactId>slf4j-simple</artifactId>
         </dependency>
     </dependencies>
+    <build>
+        <plugins>
+            <plugin>
+                <groupId>org.codehaus.mojo</groupId>
+                <artifactId>exec-maven-plugin</artifactId>
+                <configuration>
+                    <mainClass>${mainClass}</mainClass>
+                </configuration>
+            </plugin>
+        </plugins>
+    </build>
 </project>

experimental/lambda/src/main/java/io/serverlessworkflow/impl/executors/func/JavaForExecutorBuilder.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.impl.executors.func;
 
 import static io.serverlessworkflow.impl.executors.func.JavaFuncUtils.safeObject;

experimental/lambda/src/main/java/io/serverlessworkflow/impl/executors/func/JavaListenExecutorBuilder.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.impl.executors.func;
 
 import static io.serverlessworkflow.impl.executors.func.JavaFuncUtils.predObject;

experimental/lambda/src/main/java/io/serverlessworkflow/impl/executors/func/JavaSwitchExecutorBuilder.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.impl.executors.func;
 
 import static io.serverlessworkflow.impl.executors.func.JavaFuncUtils.predObject;

fluent/agentic/src/test/java/io/serverlessworkflow/fluent/agentic/WorkflowTests.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.fluent.agentic;
 
 import static io.serverlessworkflow.fluent.agentic.Agents.*;

generators/types/pom.xml

@@ -19,28 +19,4 @@
       </dependency>
 
     </dependencies>
-    <build>
-        <plugins>
-            <plugin>
-                <groupId>com.spotify.fmt</groupId>
-                <artifactId>fmt-maven-plugin</artifactId>
-                <configuration>
-                    <sourceDirectory>src/main/java</sourceDirectory>
-                    <testSourceDirectory>src/test/java</testSourceDirectory>
-                    <verbose>false</verbose>
-                    <filesNamePattern>.*\.java</filesNamePattern>
-                    <skip>false</skip>
-                    <skipSortingImports>false</skipSortingImports>
-                    <style>google</style>
-                </configuration>
-                <executions>
-                    <execution>
-                        <goals>
-                            <goal>format</goal>
-                        </goals>
-                    </execution>
-                </executions>
-            </plugin>
-        </plugins>
-    </build>
 </project>

impl/core/src/main/java/io/serverlessworkflow/impl/events/TypeEventRegistration.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.impl.events;
 
 import io.cloudevents.CloudEvent;

impl/core/src/main/java/io/serverlessworkflow/impl/events/TypeEventRegistrationBuilder.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.impl.events;
 
 public record TypeEventRegistrationBuilder(String type, CloudEventPredicate cePredicate)

impl/core/src/main/java/io/serverlessworkflow/impl/expressions/RuntimeDescriptor.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.impl.expressions;
 
 import java.util.Map;

impl/core/src/main/java/io/serverlessworkflow/impl/lifecycle/TaskCompletedEvent.java

@@ -13,7 +13,6 @@
  * See the License for the specific language governing permissions and
  * limitations under the License.
  */
-
 package io.serverlessworkflow.impl.lifecycle;
 
 import io.serverlessworkflow.impl.TaskContext;