chore: Enable JavaDoc Aggregate with Delombok

.github/dependabot.yaml

@@ -36,8 +36,6 @@ updates:
       - dependency-name: 'com.github.ekryd.sortpom:sortpom-maven-plugin'
       # used by deprecated code only, not worth updating for now
       - dependency-name: 'org.apache.axis2:*'
-      # newer versions cause issues with our release process
-      - dependency-name: 'org.apache.maven.plugins:maven-javadoc-plugin'
       # Ignore problematic license versions
       - dependency-name: 'com.sap.cloud.security:java-security'
         versions: ['3.6.1', '3.6.2']

.github/workflows/javadoc.yaml

@@ -0,0 +1,110 @@
+name: JavaDoc to Documentation Portal
+
+on:
+  workflow_dispatch:
+    inputs:
+      branch:
+        description: 'Branch/Commit/Tag for JavaDoc'
+        required: true
+        default: 'main'
+
+env:
+  JAVA_VERSION: 17
+  DOCS_REPO: SAP/cloud-sdk
+  PROJECTS: "!:rfc,!:dwc-cf,!:datamodel-metadata-generator,!:odata-generator,!:odata-generator-maven-plugin,!:odata-generator-utility,!:odata-v4-generator,!:odata-v4-generator-maven-plugin,!:s4hana-connectivity,!:soap,!:testutil,!:s4hana-core"
+
+jobs:
+  build:
+    name: "JavaDoc to Documentation Portal"
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: "Prepare git"
+        run: |
+          git config --global user.email "[email protected]"
+          git config --global user.name "SAP Cloud SDK Bot"
+
+      - name: "Checkout Repository"
+        uses: actions/checkout@v4
+        with:
+          fetch-depth: 0
+
+      - name: "Switch branch"
+        run: git checkout "${{ github.event.inputs.branch || 'main' }}"
+
+      - name: "Set up JDK 17"
+        uses: actions/setup-java@v4
+        with:
+          java-version: '17'
+          distribution: 'temurin'
+          cache: 'maven'
+
+      - name: "Determine Versions"
+        id: determine-version
+        run: |
+          echo "MAJOR_VERSION=$(jq -r '.version' latest.json | cut -d '.' -f 1)" >> $GITHUB_OUTPUT
+          echo "CURRENT_VERSION=$(jq -r '.version' latest.json" >> $GITHUB_OUTPUT
+
+      - name: "Install project (skip tests)"
+        run: mvn install -DskipTests --quiet
+
+      - name: "Process sources"
+        run: mvn process-sources -Drelease --fail-at-end --projects "${PROJECTS}" --quiet
+
+      - name: "Copy delombok sources"
+        run: find . -type d -path "*/target/delombok" -exec sh -c 'cp -r "$1"/* "$(dirname $(dirname "$1"))/src/main/java/"' _ {} \;
+
+      - name: "Generate aggregated Javadoc"
+        run: mvn clean javadoc:aggregate -Drelease -Djava.failOnWarning=false --projects "${PROJECTS}" --quiet
+
+      - name: "Checkout Docs Repository"
+        uses: actions/checkout@v4
+        with:
+          repository: ${{ env.DOCS_REPO }}
+          path: .cloud-sdk-docs
+          token: ${{ secrets.BOT_SDK_JS_FOR_DOCS_REPO_PR }}
+
+      - name: "Replace JavaDoc"
+        id: replace-javadoc
+        run: |
+          TARGET_DIR=./.cloud-sdk-docs/static/java-api/v${{ steps.determine-version.outputs.MAJOR_VERSION }}
+
+          ls -lA target
+          rm -rf $TARGET_DIR
+          mkdir -p $TARGET_DIR
+          mv target/reports/apidocs/* $TARGET_DIR
+
+          cd ./.cloud-sdk-docs
+          git add -A .
+
+          CHANGED_FILES="$(git status -s)"
+          if [[ -z "$CHANGED_FILES" ]]; then
+              echo "[DEBUG] No changes to API docs detected, skipping Pull Request creation."
+              echo "CREATE_PR=false" >> $GITHUB_OUTPUT
+              exit 0
+          fi
+
+          echo "CREATE_PR=true" >> $GITHUB_OUTPUT
+          BRANCH_NAME=java/release-docs-${{ steps.determine-version.outputs.CURRENT_VERSION }}
+          echo "BRANCH_NAME=$BRANCH_NAME" >> $GITHUB_OUTPUT
+
+          git switch --create $BRANCH_NAME
+          git commit -m "chore: Update JavaDocs for release ${{ steps.determine-version.outputs.CURRENT_VERSION }}"
+          COMMIT_SHA=$(git log -1 --pretty=format:"%H")
+          echo "COMMIT_SHA=$COMMIT_SHA" >> $GITHUB_OUTPUT
+
+          git push origin $BRANCH_NAME
+
+      - name: "Create JavaDoc PR"
+        id: create-javadoc-pr
+        if: ${{ steps.replace-javadoc.outputs.CREATE_PR == 'true' }}
+        working-directory: ./.cloud-sdk-docs
+        run: |
+          PR_TITLE="Java: Update JavaDocs for release ${{ needs.bump-version.outputs.release-version }}"
+          PR_BODY="Replace the contents of v${{ steps.determine-version.outputs.MAJOR_VERSION }} API docs with the latest release of the SDK."
+
+          PR_URL=$(gh pr create --title "$PR_TITLE" --body "$PR_BODY" --repo "${{ env.DOCS_REPO }}")
+          echo "PR_URL=$PR_URL" >> $GITHUB_OUTPUT
+          echo "PR: $PR_URL" >> $GITHUB_STEP_SUMMARY
+        env:
+          GH_TOKEN: ${{ secrets.BOT_SDK_JS_FOR_DOCS_REPO_PR }}

.github/workflows/perform-release.yml

@@ -24,6 +24,7 @@ jobs:
       code-branch: ${{ steps.determine-branch-names.outputs.CODE_BRANCH_NAME }}
       docs-branch: ${{ steps.determine-branch-names.outputs.DOCS_BRANCH_NAME }}
       release-notes-branch: ${{ steps.determine-branch-names.outputs.RELEASE_NOTES_BRANCH_NAME }}
+      release-javadoc-branch: ${{ steps.determine-branch-names.outputs.RELEASE_JAVADOC_BRANCH_NAME }}
       release-tag: ${{ steps.determine-branch-names.outputs.RELEASE_TAG }}
       release-commit: ${{ steps.determine-branch-names.outputs.RELEASE_COMMIT }}
     permissions: write-all # contents and push are needed to see the draft release
@@ -37,12 +38,14 @@ jobs:
           RELEASE_TAG=rel/$RELEASE_VERSION
           RELEASE_COMMIT=$(gh release view $RELEASE_TAG --repo ${{github.repository}} --json targetCommitish --jq '.targetCommitish')
           RELEASE_NOTES_BRANCH_NAME=java/release-notes-$RELEASE_VERSION
+          RELEASE_JAVADOC_BRANCH_NAME=java/release-docs-$RELEASE_VERSION
 
           echo "CODE_BRANCH_NAME=$CODE_BRANCH_NAME" >> $GITHUB_OUTPUT
           echo "RELEASE_VERSION=$RELEASE_VERSION" >> $GITHUB_OUTPUT
           echo "RELEASE_TAG=$RELEASE_TAG" >> $GITHUB_OUTPUT
           echo "RELEASE_COMMIT=$RELEASE_COMMIT" >> $GITHUB_OUTPUT
           echo "RELEASE_NOTES_BRANCH_NAME=$RELEASE_NOTES_BRANCH_NAME" >> $GITHUB_OUTPUT
+          echo "RELEASE_JAVADOC_BRANCH_NAME=$RELEASE_JAVADOC_BRANCH_NAME" >> $GITHUB_OUTPUT
 
           echo -e "[DEBUG] Current GITHUB_OUTPUT:\n$(cat $GITHUB_OUTPUT)"
         env:
@@ -82,6 +85,18 @@ jobs:
               \"Build Cloud SDK Documentation\": [\"dependabot\"]
             }
 
+      - name: "Check Whether JavaDoc PR Can Be Merged"
+        if: ${{ inputs.skip-pr-merge != 'true' }}
+        uses: ./.github/actions/pr-is-mergeable
+        with:
+          pr-ref: ${{ steps.determine-branch-names.outputs.RELEASE_JAVADOC_BRANCH_NAME }}
+          repo: ${{ env.DOCS_REPO }}
+          token: ${{ secrets.BOT_SDK_JS_FOR_DOCS_REPO_PR }}
+          excluded-check-runs: |
+            {
+              \"Build Cloud SDK Documentation\": [\"dependabot\"]
+            }
+
   release:
     name: "Release"
     needs: [ prerequisites ]
@@ -136,5 +151,11 @@ jobs:
       - name: "Merge Release Notes PR"
         if: ${{ inputs.skip-pr-merge != 'true' }}
         run: gh pr merge --squash "${{ needs.prerequisites.outputs.release-notes-branch }}" --delete-branch --repo "${{ env.DOCS_REPO }}"
+        env:
+          GH_TOKEN: ${{ secrets.BOT_SDK_JS_FOR_DOCS_REPO_PR }}
+
+      - name: "Merge JavaDoc PR"
+        if: ${{ inputs.skip-pr-merge != 'true' }}
+        run: gh pr merge --squash "${{ needs.prerequisites.outputs.release-javadoc-branch }}" --delete-branch --repo "${{ env.DOCS_REPO }}"
         env:
           GH_TOKEN: ${{ secrets.BOT_SDK_JS_FOR_DOCS_REPO_PR }}

.github/workflows/prepare-release.yaml

@@ -154,6 +154,26 @@ jobs:
         env:
           GH_TOKEN: ${{ github.token }}
 
+  create-javadoc-aggregated-pr:
+    needs: [ create-release ]
+    name: "Create Aggregated JavaDoc PR on Documentation Portal"
+    runs-on: ubuntu-latest
+    permissions:
+      actions: write # needed to trigger the ci-build workflow
+      statuses: write # needed to update the commit status
+    steps:
+      - name: "Checkout repository"
+        uses: actions/checkout@v5
+        with:
+          ref: ${{ needs.create-release.outputs.release-name }}
+      - name: "Trigger workflow (ignore failures)"
+        uses: ./.github/actions/trigger-workflow
+        continue-on-error: true
+        with:
+          workflow: javadoc.yaml
+          workflow-ref: main
+          parameters: -f branch=${{ needs.create-release.outputs.release-name }}
+
   create-release-notes-pr:
     name: "Create Release Notes PR"
     needs: [ bump-version, run-ci ]
@@ -263,6 +283,7 @@ jobs:
           PR_URL=$(gh pr create --title "Release ${{ needs.bump-version.outputs.release-version }}" --body "## TODOs
           - [ ] Review the changes in [the release commit]($COMMIT_URL)
           - [ ] Review **and approve** the [Release Notes PR](${{ needs.create-release-notes-pr.outputs.pr-url }})
+          - [ ] Review **and approve** the [JavaDoc PR](https://github.com/SAP/cloud-sdk/pulls?q=is%3Aopen+is%3Apr+author%3Abot-sdk-js+Update+JavaDocs)
           - [ ] Review the [Draft Release](${{ needs.create-release.outputs.release-url }})
           - [ ] Review **and approve** this PR
           - [ ] Once all tests of this PR are green, trigger the [Perform Release Workflow](${{ github.event.repository.html_url }}/actions/workflows/perform-release.yml)

dependency-bundles/bom/pom.xml

@@ -345,7 +345,7 @@
 						<plugin>
 							<groupId>org.apache.maven.plugins</groupId>
 							<artifactId>maven-javadoc-plugin</artifactId>
-							<version>3.11.2</version>
+							<version>3.12.0</version>
 							<executions>
 								<execution>
 									<id>javadoc-jar</id>

dependency-bundles/modules-bom/pom.xml

@@ -272,7 +272,7 @@
 						<plugin>
 							<groupId>org.apache.maven.plugins</groupId>
 							<artifactId>maven-javadoc-plugin</artifactId>
-							<version>3.11.2</version>
+							<version>3.12.0</version>
 							<executions>
 								<execution>
 									<id>javadoc-jar</id>

pom.xml

@@ -515,7 +515,7 @@
 				<plugin>
 					<groupId>org.apache.maven.plugins</groupId>
 					<artifactId>maven-javadoc-plugin</artifactId>
-					<version>3.11.2</version>
+					<version>3.12.0</version>
 				</plugin>
 				<plugin>
 					<groupId>com.sap.cloud.sdk.datamodel</groupId>
@@ -1015,7 +1015,6 @@
 										<packages>com.sap.cloud.sdk.s4hana*</packages>
 									</group>
 								</groups>
-								<sourcepath>${project.basedir}/target/delombok</sourcepath>
 								<overview>${project.rootdir}/javadoc.overview.html</overview>
 							</configuration>
 							<executions>
@@ -1024,6 +1023,9 @@
 									<goals>
 										<goal>jar</goal>
 									</goals>
+									<configuration>
+										<sourcepath>${project.basedir}/target/delombok</sourcepath>
+									</configuration>
 								</execution>
 							</executions>
 						</plugin>