Skip to content

build: clarify incubation status in release notes and Javadoc - #533

Merged
hsluoyz merged 2 commits into
apache:masterfrom
EmryZhang:prepare-jcasbin-1.100.0-docs
Sep 19, 2026
Merged

hsluoyz merged 2 commits into
apache:masterfrom
EmryZhang:prepare-jcasbin-1.100.0-docs

Conversation

@EmryZhang

@EmryZhang EmryZhang commented Sep 17, 2026

Copy link
Copy Markdown
Contributor

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.yml and pom.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 extracted-source Java 8 / Maven 3.9.16 clean verify cobertura:cobertura: 338 ordinary tests and 338 coverage tests, no failures, errors or skips.
  • Three JARs inspected; 210 non-frame Javadoc pages contain the disclaimer; POM metadata checked.
  • Eleven existing release-verifier tests passed with mocked GPG/network; three workflows passed actionlint (ShellCheck disabled); actual RC/final notes generated and checked.
  • Source RAT: 218 files accounted for (214 approved standard files, 3 notice files, 1 project-logo binary), with no custom exclusions.

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.

@codecov-commenter

codecov-commenter commented Sep 17, 2026

Copy link
Copy Markdown

Codecov Report

✅ All modified and coverable lines are covered by tests.
✅ Project coverage is 70.58%. Comparing base (8d904d9) to head (676aa4b).

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.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:
  • ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.

@hsluoyz hsluoyz left a comment

Copy link
Copy Markdown
Member

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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-javadocs runs during package, so mvn clean verify now requires a second JDK plus a toolchains.xml on every contributor's and every release voter's machine. If the toolchain isn't found, the plugin falls back to the JDK 8 javadoc, which rejects --legal-notices / --no-fonts, so the build fails outright. CI only passes because setup-java writes 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.py hardcodes the exact JDK 25 GA asset list, jQuery v3.7.1, jQuery UI - v1.14.1 and javadoc (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 have test_verify_release.py as a precedent.
  • The maven-enforcer-plugin pin and the three overridden transitive dependencies of maven-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 use Apache jCasbin (Incubating), consistent with the name we already set in 8d904d9, rather than Apache 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's META-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.yml change appending the ## Apache Incubator section and the downloads/verification links to the generated release notes. It's small, correct, and the paths match verify_release.py and 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.

@EmryZhang EmryZhang changed the title build: complete incubation display and documentation licensing build: clarify incubation status in release notes and Javadoc Sep 19, 2026
@hsluoyz
hsluoyz merged commit 2d95932 into apache:master Sep 19, 2026
1 check passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants