From a7eb2a48faf5117cabf72e468bc73f88baf09895 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Wed, 17 Jun 2026 00:27:20 +0100 Subject: [PATCH 1/2] Archive completed task --- .agents/tasks/{ => archive}/version-guard-aux-base-branches.md | 0 1 file changed, 0 insertions(+), 0 deletions(-) rename .agents/tasks/{ => archive}/version-guard-aux-base-branches.md (100%) diff --git a/.agents/tasks/version-guard-aux-base-branches.md b/.agents/tasks/archive/version-guard-aux-base-branches.md similarity index 100% rename from .agents/tasks/version-guard-aux-base-branches.md rename to .agents/tasks/archive/version-guard-aux-base-branches.md From d2164dfb29597e31a08be22769027505d8b90c26 Mon Sep 17 00:00:00 2001 From: Alexander Yevsyukov Date: Wed, 17 Jun 2026 00:27:28 +0100 Subject: [PATCH 2/2] Add task document --- .agents/tasks/java-21-compatibility-plan.md | 170 ++++++++++++++++++++ 1 file changed, 170 insertions(+) create mode 100644 .agents/tasks/java-21-compatibility-plan.md diff --git a/.agents/tasks/java-21-compatibility-plan.md b/.agents/tasks/java-21-compatibility-plan.md new file mode 100644 index 000000000..d5d7c20dc --- /dev/null +++ b/.agents/tasks/java-21-compatibility-plan.md @@ -0,0 +1,170 @@ +# Java Compatibility Testing Implementation Plan +**For SpineEventEngine/config Shared Configuration** + +**Objective**: Extend the shared CI configuration to test Java 17 (baseline) + Java 21 (and optionally 25) compatibility across the SDK family, particularly for SpineEventEngine SDK products including on Google Cloud Platform. + +**Status**: Current workflows pin to Java 17 (Zulu) with `actions/setup-java` + `gradle/actions/setup-gradle`. + +**Priority**: High — Aligns with enterprise/GCP adoption trends while maintaining broad compatibility. + +--- + +## 1. Preparation (1-2 hours) + +### 1.1 Review Current State +- **Java baseline**: Java 17 (see `gradle.properties`, `build-on-ubuntu.yml`, `publish.yml`). +- **Toolchains**: Already enabled via `org.gradle.java.installations.auto-detect=true` and `auto-download=true`. +- **Workflows**: Located in `.github-workflows/` (copied to consumer `.github/workflows/` via `./config/pull`). +- **Key files to update**: + - `.github-workflows/build-on-ubuntu.yml` (main CI) + - `.github-workflows/publish.yml` (keep Java 17 for publishing) + - `buildSrc/` (if custom tasks/plugins need toolchain awareness) + - `gradle.properties` (optional tweaks) + - `build.gradle.kts` (in `config` and consumers) + +**Action**: Clone this repo locally, run `./gradlew tasks --all` and inspect `buildDependants` task. + +--- + +## 2. Gradle Configuration Updates + +### 2.1 Update `build.gradle.kts` (in `config` and propagate) +Add or enhance toolchain and test tasks: + +```kotlin +java { + toolchain { + languageVersion = JavaLanguageVersion.of(17) + } +} + +// Register compatibility test tasks (optional but useful) +tasks.register("testJava21", Test::class) { + javaLauncher = javaToolchains.launcherFor { + languageVersion = JavaLanguageVersion.of(21) + } + // Group with other test tasks +} +``` + +**Action**: Add similar blocks where needed. Test locally with `./gradlew testJava21`. + +--- + +## 3. GitHub Actions Workflow Updates (Core Change) + +### 3.1 Update `build-on-ubuntu.yml` → Matrix Strategy + +Replace the single-job setup with: + +```yaml +name: Ubuntu CI + +on: + push: + branches: [master] + pull_request: + +jobs: + test: + name: Test on Java ${{ matrix.java }} + runs-on: ubuntu-latest + strategy: + matrix: + java: ['17', '21'] # Add '25' later + fail-fast: false + + steps: + - uses: actions/checkout@v6 + with: + submodules: 'true' + + - name: Setup Java ${{ matrix.java }} + uses: actions/setup-java@v5 + with: + distribution: 'temurin' # Preferred for broad compatibility (or keep 'zulu') + java-version: ${{ matrix.java }} + # NO cache: 'gradle' — handled by setup-gradle + + - name: Setup Gradle + uses: gradle/actions/setup-gradle@v6 + with: + cache-read-only: ${{ matrix.java != '17' }} # Primary version owns cache writes + + - name: Build & Test + run: ./gradlew build dokkaGenerate --stacktrace + + - name: Publish Test Report + uses: mikepenz/action-junit-report@v4.0.3 + if: always() + with: + report_paths: '**/build/test-results/**/TEST-*.xml' + require_tests: true + + - name: Upload code coverage + uses: codecov/codecov-action@v4 + with: + token: ${{ secrets.CODECOV_TOKEN }} + fail_ci_if_error: true +``` + +**Notes**: +- Keep publishing job on Java 17 only. +- Consider adding `macos-latest` or Windows matrix later for full cross-platform. + +--- + +## 4. Implementation Steps (Actionable Checklist) + +1. **Branch & Edit** + - Create branch `feature/java-21-compatibility` in `config`. + +2. **Update Shared Workflows** (`.github-workflows/`) + - Modify `build-on-ubuntu.yml` as above. + - Review `publish.yml` (keep pinned to 17). + - Update any other workflows referencing Java version. + +3. **Enhance Gradle** + - Add toolchain + test tasks in `build.gradle.kts`. + - Document supported versions in `README.md`. + +4. **Local Validation** + - `./gradlew clean build` (Java 17) + - `./gradlew testJava21` + - Run `./gradlew buildDependants` to validate against `base`, `base-types`, `core-jvm`. + +5. **Test in Consumer Repo** + - In a test SDK repo: Update submodule → `./config/pull` → Push PR and verify matrix runs. + +6. **Merge & Propagate** + - Merge to `master`. + - Update all SDK repos via `pull` script. + - Monitor first few PRs. + +7. **GCP-Specific Testing (Optional Phase 2)** + - Add job deploying test service to Cloud Run with Java 21 runtime. + - Use Temurin/Corretto distributions. + +--- + +## 5. Risks & Mitigations + +- **Breaking changes 17→21**: Monitor deprecations (Security Manager, etc.). Use `--release 17` for compilation. +- **Cache conflicts**: Strict use of `cache-read-only`. +- **Build time**: Matrix increases time — acceptable for compatibility. +- **Third-party libs**: Ensure dependencies support Java 21. + +--- + +## 6. Success Criteria +- All matrix jobs pass on PRs. +- SDK runs on Java 17 and 21+ (verified locally + GCP). +- Documentation updated with compatibility matrix. +- No regression in existing Java 17 consumers. + +**Estimated Effort**: 4-8 hours + validation time. + +**Next Steps**: Start with workflow update and test locally. + +--- +*Document generated for SpineEventEngine/config — Markdown format.*