Document how to verify the ThingsBoard compile-only surface - #121
Open
PDGGK wants to merge 1 commit into
Open
Conversation
The iotdb-thingsboard-table module implements ThingsBoard storage SPIs but cannot depend on ThingsBoard at build time: neither org.thingsboard.common:data nor org.thingsboard:dao is published to Maven Central. src/provided/java therefore carries a compile-only surface of the types the module touches, excluded from the built jar so the real classpath supplies them at runtime. That keeps the module buildable for everyone, at the cost that the surface can drift from the real interfaces with nothing in the default build noticing. This adds the procedure for checking that it has not: build the two ThingsBoard modules locally, swap the compile-only surface for the real artifacts, and run the suite. The procedure is deliberately not wired into the default build, since that would require every contributor and every CI run to clone and build ThingsBoard first. Includes a control for confirming the surface was actually removed -- a green build proves nothing if the compile-only sources are still on the source path -- and records the result against ThingsBoard 4.3.1.2: 190 unit tests and 57 container integration tests green, no drift. Signed-off-by: Zihan Dai <99155080+PDGGK@users.noreply.github.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Why
iotdb-thingsboard-tableimplements ThingsBoard storage SPIs but cannot depend on ThingsBoard at build time — neitherorg.thingsboard.common:datanororg.thingsboard:daois published to Maven Central (numFound 0for both).src/provided/javatherefore carries a compile-only surface of the types the module touches, excluded from the built jar so the real ThingsBoard classpath supplies them at runtime.That keeps the module buildable for everyone. Its one cost is that a hand-written surface can drift from the real interfaces and nothing in the default build would notice.
What this adds
A procedure for checking that it has not drifted: build the two ThingsBoard modules locally, swap the compile-only surface for the real artifacts, run the suite. It is deliberately not wired into the default build — doing so would require every contributor and every CI run to clone and build ThingsBoard first, which is the situation the compile-only surface exists to avoid.
Two things I tried to make it earn its place:
Compiling 58 source fileswith the surface,19without — so a reader can catch the procedure silently not having taken effect.commons-lang3must match the version ThingsBoard pins (3.18.0 for 4.3.1.2); with an older one, every test in a suite touchingEntityTypefails at static initialisation withNoClassDefFoundError, which looks like drift and is not. Andverifyrunsapache-rat, so a file added while working through the procedure fails the build after the tests have passed.Result recorded in the doc
Against ThingsBoard 4.3.1.2, with the compile-only surface removed and the real artifacts on the classpath: 190 unit tests and 57 container integration tests green, no drift — every type matched and all three
implementsclauses bound against the real interfaces.This does not establish that ThingsBoard as a whole runs on this DAO; the doc says so explicitly.
Notes for review
Documentation only — one new file, no build or code changes, so no workflow approval is needed for this one. Both commands in it were run exactly as written, without skip flags, and
apache-ratpasses with the file in place.