kie-issues#2300: Improve kie-api Javadoc generation and API compatibility reporting - #6704
kie-issues#2300: Improve kie-api Javadoc generation and API compatibility reporting#6704yesamer wants to merge 45 commits into
Conversation
…nsive documentation
yesamer
changed the title
There was a problem hiding this comment.
Pull request overview
This PR re-enables Javadoc jar generation for kie-api, refreshes the public API documentation (overview, deprecation metadata, @since/@apiNote tags, missing @Overrides) and re-introduces automated API compatibility tooling (RevAPI as an enforced check during verify, JApiCmp as a report-only goal during package). It also adds a top-level CHANGELOG.md and kie-api/CHANGELOG.md and an kie-api/README.md describing the new tooling.
Changes:
- Added Javadoc/RevAPI/JApiCmp plugin configuration in
kie-api/pom.xmland supporting properties inbuild-parent/pom.xml; rewrotekie-api/src/build/revapi-config.jsonto the new array-based extension format and excludedorg.kie.internal.*/org.kie.api.internal.*. - Enriched many existing
@DeprecatedAPIs withsince/forRemovalmetadata and clarified Javadoc; added@Override,@apiNote,@sincetags across runtime/conf/event interfaces and refreshedoverview.html. - Added top-level and module-level
CHANGELOG.mdfiles plus a newkie-api/README.mddocumenting the API stability process and tooling.
Reviewed changes
Copilot reviewed 48 out of 48 changed files in this pull request and generated 9 comments.
Show a summary per file
| File | Description |
|---|---|
| kie-api/src/main/javadoc/overview.html | Rewords overview and unescapes several angle-bracket characters |
| kie-api/src/main/java/org/kie/api/runtime/StatelessKieSession.java | Adds @since/@apiNote Javadoc |
| kie-api/src/main/java/org/kie/api/runtime/RuntimeSession.java | Adds class-level Javadoc with @since 10.1.0 |
| kie-api/src/main/java/org/kie/api/runtime/rule/EntryPoint.java | Expands deprecation metadata for retract |
| kie-api/src/main/java/org/kie/api/runtime/process/NodeInstanceContainer.java | Adds Javadoc to getSerializableNodeInstances |
| kie-api/src/main/java/org/kie/api/runtime/KieSession.java | Adds since/forRemoval to getId |
| kie-api/src/main/java/org/kie/api/runtime/KieRuntimeBuilder.java | Adds Javadoc for stateless session factories |
| kie-api/src/main/java/org/kie/api/runtime/KieRuntime.java | Adds class-level Javadoc |
| kie-api/src/main/java/org/kie/api/runtime/KieContext.java | Updates deprecated getKnowledgeRuntime Javadoc |
| kie-api/src/main/java/org/kie/api/runtime/conf/*.java | Adds @Override on getPropertyName in many option enums/classes |
| kie-api/src/main/java/org/kie/api/persistence/jpa/KieStoreServices.java | Updates deprecated overload Javadoc |
| kie-api/src/main/java/org/kie/api/management/KieBaseConfigurationMonitorMBean.java | Adds since/forRemoval to deprecated MBean methods |
| kie-api/src/main/java/org/kie/api/KieServices.java | Updates deprecated newKieBaseConfiguration overload Javadoc |
| kie-api/src/main/java/org/kie/api/io/ResourceType.java | Updates deprecation metadata for DRT |
| kie-api/src/main/java/org/kie/api/event/process/*.java | Adds Javadoc / @apiNote to process event interfaces |
| kie-api/src/main/java/org/kie/api/conf/*.java | Adds @Override on option getters; updates deprecation Javadoc on Option/OptionsConfiguration |
| kie-api/src/main/java/org/kie/api/command/KieCommands.java | Adds Javadoc for newBatchExecution and newApplyPmmlModel |
| kie-api/src/build/revapi-config.json | Migrates RevAPI config to new format and adds package excludes |
| kie-api/README.md | Adds new module-level README documenting API tooling |
| kie-api/pom.xml | Drops apiviz profile, adds RevAPI/JApiCmp plugin executions, refreshes Javadoc plugin config |
| kie-api/CHANGELOG.md | Adds module-level changelog |
| CHANGELOG.md | Adds project-level changelog |
| build-parent/pom.xml | Bumps Javadoc plugin, adds RevAPI/JApiCmp version & branding properties, registers apiNote Javadoc tag |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Rikkola
left a comment
Rikkola
left a comment
There was a problem hiding this comment.
Looks good. My only worry is the changelog not being up to date on long term. If we ever get more power on the AI reviews we should add that file as something to keep an eye on for each PR.
|
@Rikkola yes, good point. I'll think about that. |
|
@yesamer I don't think we have access for something like that right now, but there are other areas too that could use some overwatch. |
gitgabrio
left a comment
gitgabrio
left a comment
There was a problem hiding this comment.
HI @yesamer , thanks for the hard work: great stuff!
I think the only missing bit is to fix the "since" attribute in some javadoc: please keep in mind that most of the "public" APIs are pretty old, surely older then any 10.x release.
| /** | ||
| * KieRuntime provides runtime capabilities for rule and process execution. | ||
| * Extends RuntimeSession for common session operations. | ||
| * @since 10.1.0 |
There was a problem hiding this comment.
HI @yesamer
I'm afraid there is some sort of misalignment about introduction version. I'm sure KieRuntime is way older than 10.1.0, and this is demonstrated by the following (e.g.):
@Deprecated(since = "6.0.0", forRemoval = true)
KieRuntime getKnowledgeRuntime();I think the confusion may be due to the fact that at a given point multiple repositories get merged in a single one.
Please take a look at 6.5.0 API (again, e.g.)
There was a problem hiding this comment.
@gitgabrio Removed @since because of same reason of #6704 (comment)
| * Creates a command to apply a PMML model. | ||
| * @param request the PMML request data as a Map | ||
| * @return the command | ||
| * @since 10.2.0 |
There was a problem hiding this comment.
@yesamer
This was introduced in some 8.x version (see 8.39.0 FInal API
There was a problem hiding this comment.
@gitgabrio In this case, it is correct. The API changed from:
newApplyPmmlModel(PMMLRequestData request) to:
newApplyPmmlModel(Map<String, Object> request);
in version 10.2.0
The latter is considered a new API that replaces the previous one (which would have been deprecated). Removing the old API results in a breaking change for the end user.
| * call dispose(). While the main way to work with this class is via the BatchExecution Command as supported by the CommandExecutor interface, | ||
| * two convenience methods are provided for when simple object insertion is all that's required. | ||
| * Extends RuntimeSession for common session operations. | ||
| * @since 10.1.0 |
There was a problem hiding this comment.
@gitgabrio Thank you, I guess the mistake was this interface was refactored in 10.1.0 (the extended interfaces were different). I double checked, and despite the change, the API contract didn't change - so I'll remove the since parameter which is misleading.
Closes apache/incubator-kie-issues#2300
Summary
This PR restores and improves Javadoc generation and API compatibility reporting for kie-api.
The changes ensure that kie-api publishes its Javadoc jar during regular builds, refresh public API documentation for the current JDK baseline, and reintroduce automated API compatibility checks using RevAPI and JApiCmp. In addition, the PR improves the documentation of long-deprecated APIs by adding clearer deprecation details, including explicit
sinceandforRemovalmetadata.What changed
@Deprecated(since = ..., forRemoval = true)metadataverifyagainst the latest released kie-api artifact@Deprecatedannotations as documentation-only changes@Overrideannotations where appropriateWhy
This aligns kie-api with the goal of having reliable Javadoc publication and automated API compatibility reporting while keeping the compatibility tooling focused on meaningful public API changes.
It also improves the quality of the published API documentation by clarifying intended usage, session semantics, and the status of long-deprecated methods without introducing functional API changes.