build: clarify incubation status in release notes and Javadoc - #533
Conversation
Codecov Report✅ All modified and coverable lines are covered by tests. Additional details and impacted files@@ Coverage Diff @@
## master #533 +/- ##
=======================================
Coverage 70.58% 70.58%
=======================================
Files 65 65
Lines 3179 3179
Branches 580 580
=======================================
Hits 2244 2244
Misses 756 756
Partials 179 179 ☔ View full report in Codecov by Harness. 🚀 New features to boost your workflow:
|
hsluoyz
left a comment
There was a problem hiding this comment.
Thanks for the detailed write-up. I went through the full diff, and I'd like to split this into what I'm happy to take and what I'd ask you to drop. As it stands I can't merge this PR.
The core issue: the Javadoc licensing problem is introduced by this PR, not fixed by it.
The javadoc tool in JDK 8 does not bundle jQuery or jQuery UI — the search feature (and jQuery) only arrived in JDK 9. Our current javadoc jar contains generated HTML plus a single stylesheet.css and script.js, so there is no third-party MIT code in it that needs a separate LICENSE. This PR switches documentation generation to JDK 25, which adds jQuery 3.7.1 / jQuery UI 1.14.1 to the jar, and then adds a 335-line LICENSE and a 91-line verifier to account for them. That's solving a problem we don't have today.
The cost of that switch is real:
attach-javadocsruns duringpackage, somvn clean verifynow requires a second JDK plus atoolchains.xmlon every contributor's and every release voter's machine. If the toolchain isn't found, the plugin falls back to the JDK 8javadoc, which rejects--legal-notices/--no-fonts, so the build fails outright. CI only passes becausesetup-javawrites toolchains for you. For a Java 8 library this is a disproportionate burden, and it makes the source release harder to verify, which works against the incubation goal.verify_javadoc.pyhardcodes the exact JDK 25 GA asset list,jQuery v3.7.1,jQuery UI - v1.14.1andjavadoc (25. Any JDK 25.0.x update that bumps jQuery will break CI and require editing both the script and the LICENSE file. The PR description mentions six rejected-input cases, but no test file is included, even though we already havetest_verify_release.pyas a precedent.- The
maven-enforcer-pluginpin and the three overridden transitive dependencies ofmaven-javadoc-plugin(commons-beanutils,plexus-utils,aircompressor) are unrelated to incubation display and shouldn't be in this PR.
POM metadata
<name>: adding "(Incubating)" is right. Please useApache jCasbin (Incubating), consistent with the name we already set in 8d904d9, rather thanApache Casbin JCasbin (Incubating).<description>: please revert. Appending the whole DISCLAIMER paragraph to the description, without even a separator after "…in Java", produces an unreadable blob on Maven Central. The DISCLAIMER file already ships in the source release and in every jar'sMETA-INF. If you want a pointer, a single sentence like "Part of Apache Casbin (Incubating)." is enough.- The
<developer>entry named "Apache Casbin (Incubating)" is a misuse of that element; that's what<organization>is for. Please remove it.
What I'd be glad to merge
- The
release.ymlchange appending the## Apache Incubatorsection and the downloads/verification links to the generated release notes. It's small, correct, and the paths matchverify_release.pyand RELEASING.md. - The
<name>change with the wording above.
If you'd like the disclaimer visible in the generated Javadoc pages, <bottom> works fine with the JDK 8 javadoc; no JDK switch is needed for that.
Could you reduce the PR to those two changes (release notes + <name>) and drop the JDK 25 toolchain, src/javadoc-legal/LICENSE, verify_javadoc.py, the plugin dependency overrides and the enforcer pin? I'll review the smaller version promptly.
The generated release notes omit the incubation disclaimer, and the POM name does not identify incubation status. This change adds the existing disclaimer to RC/final release notes, adds official source-download and verification links to final notes, and sets the POM name to
Apache jCasbin (Incubating). A Java 8-compatible Javadoc footer displays the existing disclaimer.The diff against the current base is limited to
release.ymlandpom.xml(11 additions, 1 deletion). It uses the existing Java 8 build and plugin configuration.Validation of the exact source snapshot committed in this revision:
clean verify cobertura:cobertura: 338 ordinary tests and 338 coverage tests, no failures, errors or skips.Maven downloads were cached and GPG was skipped. Existing Cobertura complexity-parser warnings remain; coverage report generation succeeded. Hosted CI passed on
676aa4b4c836928453a556092db6a63e63d08c08, including the Java 8 build, release-verifier tests and Codecov step. No signing or deployment was performed.