feat(spec): add issue resolution specification for SDK packaging version issues - #37452
Open
Conversation
…ion issues This commit introduces a new specification document addressing defects in the SDK packaging mechanism, specifically focusing on malformed version strings and incorrect dist-tags. The spec outlines the problem, reproduction steps, expected vs. actual behavior, and the impact on customers, aiming to guide the resolution process for these critical issues.
13 tasks
13 tasks
rjvelazco
previously approved these changes
Sep 8, 2026
…e doc fix rjvelazco's review on PR #37452 pointed out that react/README.md, angular/README.md, and vue/README.md currently claim installing the main package "will automatically install the required dependencies" -- a claim this fix's peerDependencies change makes unreliable, and one that was already inaccurate for @dotcms/types (a devDependency, never auto-installed even before this fix, but never called out in the docs either). Names the exact files/sections to correct, expands the required manual install list to all three affected packages (@dotcms/client, @dotcms/uve, @dotcms/types), and broadens "yarn classic" to also cover npm below v7, which has the same no-auto-install-peers behavior. Adds AC-009 to make this independently verifiable. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Discovered during implementation: main also carries examples/angular-ssr (already correctly "latest") and examples/nextjs-experiments (still "next", same defect as nextjs/vuejs) -- neither was in the original file listing. Confirmed via git ls-tree that neither exists on either LTS branch (both carry only the original four), so Defect B3's scope is unaffected. Every "four main examples" reference updated to six; the shared validation script needs no code change since it takes a path/branch generically rather than hardcoding the example list. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Developer scaffolded examples/nextjs from release-25.07.10_lts_v12 against a real 25.07.10 LTS server and found the then-current "latest" pin (resolving to 26.9.3-1) rendered correctly, including inside UVE -- no FieldUndefined errors. 1.2.0 was never independently verified and is now known to be far behind the SDK's current feature set. Backport PR: #37475 Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…010) Developer correctly objected that manually re-pinning the two existing LTS branches doesn't stop the *next* release branch (LTS or not) from being cut with the same floating-example defect -- main's examples deliberately float on "latest" by design, so any freshly-cut branch inherits that. Root-cause fix: cicd_comp_release-prepare-phase.yml (the workflow that cuts every release branch) now pins every example's @dotcms/* dependency to that release's own exact, normalized version at cut time -- correct by construction per ADR-0019's date-lockstep guarantee, no per-branch manual verification needed going forward. Adds AC-010, updates Defect B3's root-cause analysis, narrows the "no ongoing re-sync" non-goal to only cover already-existing branches (the new step handles every future one automatically), and updates Blast Radius / Verification method for the second high-blast-radius workflow this fix now touches. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
…e test The prior "verified against a real server" commit was itself based on an invalid test (a Docker container running trunk, not 25.07.10 LTS -- trunk already has every field the query needs, so nothing could have failed). Static, no-server-needed verification instead: release-25.07.10_lts_v12's GraphQL schema lacks lockedBy, lockedByName, numberContents, styleEditorSchemas, and layout metadata; @dotcms/client's query has requested all five since 2025-11-26 through 2026-05-07 (PRs #33905, #34966, #34173, #35528); @dotcms/client@1.2.0 published 2025-10-24, over a month before any of them, with no other stable release in that gap. 1.2.0 requests none of the five fields -- schema-compatible by construction, and this confirms the original issue's own guess rather than replacing it, as the previous commit's message claimed. PR #37475 corrected to match (both the pin and its description's test-plan claims). AC-005's verification method updated to prefer this static approach over a live-server test, given how easily the latter produces a false pass against the wrong build. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
Verified independently, not assumed identical to _v12 -- same static method (checked all 80 files under dotCMS/src/main/java/com/dotcms/graphql/ on release-25.07.10_lts_v16) confirms the same schema gap, so 1.2.0 applies there too. Both LTS backports (#37475, #37476) are now open. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
KevinDavilaDotCMS
added a commit
that referenced
this pull request
Sep 9, 2026
… B1/B1b) Tasks T020-T027 for spec specs/37399-sdk-packaging-version-fix. react, angular, vue, and analytics declared @dotcms/client/@dotcms/uve as regular `dependencies` -- the actual mechanism letting yarn/pnpm install a second, independently-resolved copy alongside a consumer's own pinned version, regardless of the value's correctness. Moved to `peerDependencies` (the shape `experiments` already used) so they defer to whatever the consumer already installed, matching how react-dom avoids shipping its own react. Value fixed to the "0.0.0" sentinel everywhere a sibling @dotcms/* package appears in peerDependencies (including experiments' pre-existing four entries) -- "latest" is not a valid semver range, so a local peer-dependency-satisfaction check can't evaluate it sanely regardless of what's actually installed, which was the real cause of local pre-publish testing breakage. dependencies/devDependencies keep "latest" unchanged -- masked by the publish-time rewrite (Defect A fix), no customer-facing effect. Corrected react/angular/vue's READMEs: each claimed installing the main package "will automatically install the required dependencies" -- no longer reliably true. Now lists @dotcms/client, @dotcms/uve, and @dotcms/types as required manual installs, naming yarn classic (1.x) and npm below v7 as needing this (AC-009, addresses PR #37452 review feedback). Verified with real locally-built tarballs (sdk-react + sdk-client) across npm, pnpm, and yarn classic 1.22.22: no nested duplicate @dotcms/client under react's own node_modules in any of the three -- the original duplicate-copy bug is fixed. Yarn classic correctly warns instead of auto-installing a peer that's genuinely missing from the manifest, confirming the documented behavior change is real, not hypothetical. Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>
9 tasks
Contributor
Author
|
@rjvelazco Thanks for the review — your feedback on the README docs is incorporated, both in the spec and in the implementation:
This PR is now re-opened for approval since it went through additional changes after your review (LTS root-cause fix, version-pipeline normalization, etc.) — appreciate you taking another look when you get a chance. |
KevinDavilaDotCMS
requested review from
dario-daza,
fmontes,
nicobytes,
rjvelazco and
zJaaal
September 9, 2026 18:36
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
2 participants
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.
This commit introduces a new specification document addressing defects in the SDK packaging mechanism, specifically focusing on malformed version strings and incorrect dist-tags. The spec outlines the problem, reproduction steps, expected vs. actual behavior, and the impact on customers, aiming to guide the resolution process for these critical issues.
Proposed Changes
Checklist
Additional Info
** any additional useful context or info **
Screenshots