Release: Javadocs job fails

Problems

1. The job executes the package phase before generating java docs, which leads to taking the sources of the generated Java Open API client into account, which is generated in the test phase
2. The aggregated javadocs cannot be generated due to "error: cannot find symbol"

Why does this job start to fail now?

• Due to the new Quarkus Extension, we have to compile our sources with Java 11.
• While previously problem #1 was already present, Java 8 considered "cannot find symbol" as a warning and not as an error which leads to problem #2

Solution RE Problem #2

Add the --ignore-source-errors flag to skip "cannot find symbol" errors again

Solution ideas RE Problem #1

1. Change maven phase called from the CI job from package to compile
   • The package phase includes generating and compiling test sources whereas compile only concerns the production source code
   • Problems
     • While this works on production, it fails on the test release job: different from the actual release job, the test release job doesn't share the same maven repository with the other jobs; this is why the javadocs job cannot consume the already created artifacts and fails
     • In the test release job, the distro/sql-scripts and spring-boot/webjar modules require to unpack artifacts that need to be reconfigured so that the compile phase succeeds
2. Add -Dmaven.test.skip=true flag
   • Other than -DskipTests this flag additionally skips the test-compile phase
   • Problem: similar to the aforementioned problem, however, the job cannot consume test-jar artifacts
3. Skip the problem causing maven plugins in the open API module on -DskipTests
   • Problems
     • This solution can never be on its own since tests are still compiled when using -DskipTests flag and will fail if the generated open API client classes are not present
     •  The maven plugin build-helper-maven-plugin is a nightmare regarding configuration possibilities and cannot be skipped (note to myself: try to avoid in the future)
       • This could be solved by additionally adding the -Dmaven.test.skip=true flag; however, see the problem caused by this mentioned before
         • The upstream release job also uses -DskipTests and would run into the same problem
4. Use a new maven profile -Pjavadocs in the release job to override the open API generator and the maven compile plugin to skip compiling test sources

Decision

I think the cleanest solution is #1, which non-declaratively covers cases like this we might even introduce in the future. However, the way the release jobs are designed requires that the artifacts are either available in a shared nexus repository or created within the same job, which is not the case in the test release job.

Outlook

When transforming the release jobs into pipelines, thanks to artifact stashing, the test release pipeline could be even closer to the actual release pipeline, and we can reevaluate if solution #1 makes sense.