fix(docs): correct contradictions and fabricated APIs in backend AI-context docs - #37258
Open
jcastro-dotcms wants to merge 19 commits into
Open
fix(docs): correct contradictions and fabricated APIs in backend AI-context docs#37258jcastro-dotcms wants to merge 19 commits into
jcastro-dotcms wants to merge 19 commits into
Conversation
Core modules compile to Java 25, not 21/11; tools/dotcms-cli targets Java 11 (the conservative target), not "Java 21 features". Swapped the two syntax-example sections to match reality. Issue #37126
Same header fix as JAVA_STANDARDS.md — Java 25 for core modules, Java 11 correctly framed as the CLI's conservative target. Issue #37126
Backend compiles to Java 25, not "Java 21 runtime with Java 11 bytecode compatibility". Also fixed the CLI directory annotation, which had the same backwards claim. Issue #37126
Same fix as ARCHITECTURE_OVERVIEW.md — backend compiles to Java 25, CLI targets Java 11 (the conservative target, not an exception for newer syntax). Issue #37126
…CESS.md Troubleshooting note said Java 21; dotCMS runs on Java 25 per .sdkmanrc. Issue #37126
…PI_PATTERNS.md securityAPI.hasPermission(...) doesn't exist (3 occurrences) — replaced with the real permissionAPI.doesUserHavePermission(...). HTMLUtils (Spring, not present in this codebase) replaced with the real Xss.encodeForHTML(...). Issue #37126
permissionAPI.hasPermission(...) doesn't exist (3 call sites) — replaced with the real doesUserHavePermission(Permissionable, int, User) signature, verified against PermissionAPI.java's real PERMISSION_READ/EDIT/EDIT_PERMISSIONS constants. Issue #37126
…_PATTERNS.md The anti-pattern rule against uppercase properties contradicted its own cluster-config example. Now states the exception explicitly for dotcms-config-cluster.properties and the OpenSearch config docs. Issue #37126
…ITORING.md HealthCheckLocator (registration + query) doesn't exist — replaced with the real CDI auto-discovery pattern via HealthCheckRegistry/HealthCheckProvider, and real HealthService for querying/aggregation. HealthStatus.HEALTHY/UNHEALTHY don't exist — replaced with the real UP/DOWN values (DEGRADED/UNKNOWN also noted). @component and @scheduled are Spring annotations not used anywhere in this codebase — replaced with @ApplicationScoped and a note that dotCMS doesn't use Spring scheduling. The Elasticsearch example's ESClient/ ClusterHealthResponse/ClusterHealthStatus were fabricated — replaced with the verified real APILocator.getESIndexAPI().getClusterStats() call. Also found during final verification: the Kubernetes probe/detailed-health endpoints were documented on the wrong port/path entirely (localhost:8080/livez etc. — real is localhost:8090/dotmgt/livez, served by HealthProbeServlet on the separate management port); six health.* property names were fabricated (real convention is health.check.{name}.{property}); log level list was missing ALL. Issue #37126
…, and fake health properties in JAVA_STANDARDS.md
Per team decision: replace hardcoded Java version numbers with pointers to
the real source (.sdkmanrc, parent/pom.xml's dotcms.core.compiler.release,
tools/dotcms-cli/pom.xml's maven.compiler.release) so this doesn't go stale
again the way it just did.
Also: the fast-iteration Maven command was missing --am, which CLAUDE.md
flags as able to fail on missing in-project deps — added it. Fixed a broken
anchor link to REST_API_PATTERNS.md (real header slug is
#view-object-pattern-java-records, not #view-object-pattern-valueimmutable).
Replaced two fabricated health.* property names (found during final
verification) with the real health.check.{name}.{property} convention.
Issue #37126
… JAVA_STANDARDS_FOCUSED.md Same fixes as JAVA_STANDARDS.md: version numbers now point to the real source instead of hardcoded literals, and the two fabricated health.* property names are corrected to the real convention. Issue #37126
…ENSEARCH_MIGRATION_TEST_PLAN.md The "limited-user stack" section pointed at a docker-compose.limited-user.yml file that doesn't exist — every credential/port/script detail in that section already matched the real single-node-os-migration/docker-compose.yml exactly, so this was a wrong filename, not a missing file. Also fixed the provisioning service name (real is opensearch3-provision, not opensearch-provision), found during final verification. Scope note: this fixes only the limited-user section (3 of 7 originally flagged path occurrences). The other 4 occurrences, plus this file's "ES 7.10 + Kibana" framing more broadly, are blocked on a cross-team decision — see issue comments. Issue #37126
Found during final verification: doc said com.dotcms.rest.ResponseUtil; the real class is at com.dotcms.rest.api.v1.authentication.ResponseUtil. Would not have compiled as written. Issue #37126
…ponseUtil package in REST_API_PATTERNS_FOCUSED.md SecurityUtils.sanitizeInput(...) doesn't exist on either SecurityUtils class in the codebase — replaced with the real Xss.encodeForHTML(...). Also fixed ResponseUtil's package (real is com.dotcms.rest.api.v1.authentication.ResponseUtil), found during final verification. This file's permission-check example was already correct before this fix — it's the one place in the audited docs that had doesUserHavePermission(...) right from the start. Issue #37126
…age in SECURITY_BACKEND.md org.springframework.web.util.HtmlUtils doesn't exist in this codebase (zero Spring dependencies anywhere) — replaced with the real com.liferay.util.Xss. encodeForHTML(...). Also fixed ResponseUtil's package (real is com.dotcms.rest.api.v1.authentication.ResponseUtil), found during final verification. Issue #37126
…m in ARCHITECTURE_OVERVIEW.md Per team decision: Java/Angular versions now point to the real source (.sdkmanrc, parent/pom.xml, tools/dotcms-cli/pom.xml, core-web/package.json) instead of hardcoded literals. Also found during final verification: "Spring/CDI" for backend DI — verified zero Spring usage anywhere in this codebase (source + all poms). Corrected to CDI only, matching this same fix set's HEALTH_MONITORING.md. Issue #37126
…m in CODE_STRUCTURE.md Same fixes as ARCHITECTURE_OVERVIEW.md: Java/Angular versions now point to the real source instead of hardcoded literals, and the two fabricated "Spring/CDI" mentions are corrected to CDI only (zero Spring usage verified anywhere in this codebase). Issue #37126
…rt, and more in DOCKER_BUILD_PROCESS.md
- docker-maven-plugin and cargo-maven3-plugin versions now reference the
real ${version.*} properties instead of stale hardcoded literals
(0.43.4 -> 0.48.0, 1.10.6 -> 1.10.12)
- Removed the fabricated apt-get openjdk-11 install step and fake Dockerfile
stage name/ARG (container-base / SDKMAN_JAVA_VERSION are the real ones)
- Fixed the debug-port self-contradiction: the JMX section's "8000:8000" was
the actual bug, not the "5005" elsewhere in the doc — debug.port defaults
to 5005 in parent/pom.xml, confirmed live in 4 profile configs. Added a
callout explaining both 5005 (Maven docker-start,debug workflow) and 8000
(the base Dockerfile's own default, for CMS_JAVA_OPTS-based debugging) are
real, for different run paths, so this doesn't get "corrected" backwards
again
- Replaced the fabricated standalone ./dev-run script with the real
`just dev-run-debug` / `just dev-run-jmx-debug-glowroot` targets
- JConsole JDK-version reference now points to .sdkmanrc instead of a
hardcoded literal (per team decision)
Also found during final verification: wrong Postgres image (ankane/pgvector
-> real pgvector/pgvector:pg18, per environments/environment.properties),
and `just build-no-docker`'s description/timing didn't match its real
recipe (it's a full clean install, not the fast core-only build shown next
to it).
Issue #37126
23 tasks
Contributor
|
Claude finished @jcastro-dotcms's task in 1m 33s —— View job Code ReviewDocs-only PR. Since the stated purpose is replacing fabricated APIs with real ones, I verified each replacement against actual source rather than internal doc consistency. Verified accurate against source:
New IssuesNo issues found. Every fabricated symbol, config key, version pointer, file path, and anchor introduced by this PR resolves to real source. No new contradictions or broken links introduced. One non-blocking observation (pre-existing, not introduced here, so not flagged): in |
6 tasks
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.
Summary
Fixes M1 of the Backend AI-Context Rock (#37124) — contradictions, fabricated APIs, and stale references across Jose's slice of the backend AI context (
docs/backend/,docs/infrastructure/, a 4-filedocs/core/slice, rootCLAUDE.md). Closes acceptance criteria on #37126.Why this matters: these docs are read by AI coding assistants (and humans) as ground truth. Several of them were citing APIs, endpoints, config properties, and infrastructure details that don't exist — meaning AI-generated code following this guidance would not compile, or a human following the setup steps would hit dead ends.
What changed, by category
Java/Angular version drift —
CLAUDE.mdsaid Java 25;JAVA_STANDARDS.md,JAVA_STANDARDS_FOCUSED.md,ARCHITECTURE_OVERVIEW.md,CODE_STRUCTURE.md, andDOCKER_BUILD_PROCESS.mdstill said Java 21/11, and had the CLI's actual target (11, the most conservative in the repo) backwards as if it got newer features. All five fixed. Per a team decision made mid-fix, version numbers are no longer hardcoded — they now point to the real source (.sdkmanrc,parent/pom.xml,tools/dotcms-cli/pom.xml,core-web/package.json) so this can't silently go stale again.Fabricated APIs that would not compile:
securityAPI.hasPermission(...)/permissionAPI.hasPermission(...)(doesn't exist, 6 occurrences acrossREST_API_PATTERNS.mdandSECURITY_BACKEND.md) → realpermissionAPI.doesUserHavePermission(...)HealthCheckLocator.registerHealthCheck(...)/.getAllHealthChecks()(doesn't exist) → real CDI auto-discovery viaHealthCheckRegistry/HealthCheckProvider/HealthServiceHealthStatus.HEALTHY/UNHEALTHY(don't exist) → realUP/DOWN(DEGRADED/UNKNOWNalso noted)@Component,@Scheduled(Spring — not used anywhere in this codebase) →@ApplicationScoped(CDI) and a note explaining whyESClient,ClusterHealthResponse,ClusterHealthStatus) → the real, verifiedAPILocator.getESIndexAPI().getClusterStats()callorg.springframework.web.util.HtmlUtils/SecurityUtils.sanitizeInput(...)(both fabricated) → realcom.liferay.util.Xss.encodeForHTML(...)ResponseUtildocumented in the wrong package in 3 files → realcom.dotcms.rest.api.v1.authentication.ResponseUtilpom.xmland all ofdotCMS/src/main/java)Infrastructure/build details that didn't match reality:
docker-maven-pluginandcargo-maven3-pluginversions were stale (now reference the real${version.*}properties instead of hardcoded literals)apt-get install openjdk-11step, a fake Dockerfile stage name/ARG, and a fake standalone./dev-runscript — all replaced with what's actually in the real Dockerfile/justfiledebug.portdefaults to5005inparent/pom.xml(confirmed live in 4 profile configs) for the Mavendocker-start,debugworkflow;8000is a separate, also-real port the base Dockerfile exposes forCMS_JAVA_OPTS-based debugging on a directly-run image. Both are correct for different workflows — a callout in the doc now explains this so it doesn't get "corrected" backwards againankane/pgvector→ realpgvector/pgvector:pg18)just build-no-docker's description/timing didn't match its real recipe (it's a fullclean install, not the fast core-only build shown next to it)localhost:8080/livezetc. → real islocalhost:8090/dotmgt/livez, served on the separate management port) and six fabricatedhealth.*config property names → realhealth.check.{name}.{property}conventionOther doc-quality fixes:
JAVA_STANDARDS.md--amCONFIGURATION_PATTERNS.mdnow states its own exceptionopensearch-provision→ realopensearch3-provision) in the OpenSearch migration test plan's limited-user sectionExplicitly NOT included in this PR
OPENSEARCH_MIGRATION_TEST_PLAN.mdandOPENSEARCH_MIGRATION_TESTER_GUIDE.mdhave a separate, unrelated inconsistency (conflicting assumptions about which OpenSearch test stack is the default) that spans a cross-team infra decision, not a straightforward doc fix. That's being handled separately by Fabrizzio / Team Scout in #37292. This PR only includes the small, already-verified fix to the limited-user section's file path and service name (see above) — nothing else in those two files is touched here.How this was verified
Every fix here was checked against real source — not just internal doc consistency — including a fully independent pass with no prior context on what was "supposedly" fixed, which caught several issues the first pass missed (see full evidence trail in #37125 and #37126).
Test plan
Closes acceptance criteria on #37126. Part of #37124.
This PR fixes: #37126