Implement issue resolution specification for SDK packaging defects, a… - #37414
Open
KevinDavilaDotCMS wants to merge 6 commits into
Conversation
…ddressing malformed version strings and floating dist-tags in published packages and example apps.
13 tasks
13 tasks
rjvelazco
previously approved these changes
Sep 4, 2026
main's four example apps deliberately float on the "latest" npm dist-tag going forward (nextjs/vuejs move off "next" to match angular/astro). Running them against an old dotCMS server is now an explicit non-goal. LTS branches (release-25.07.10_lts_v12/_v16) keep the exact, compatible pin requirement unchanged, since that's what resolves Freshdesk #38677. Updates the CI guardrail and AC-004/AC-007 to be branch-aware accordingly.
…t LTS Read ADR-0019 (SDK/CMS date-lockstep versioning, accepted 2026-06-23) in full. It already prescribes exactly the leading-zero-drop fix scoped for Defect A, and its Implementation Notes require every example app -- including main's four, not only the LTS branches -- to pin an exact date version instead of a floating "latest"/"next" tag. Reverts the prior revision that had main intentionally track "latest". Adds an explicit non-goal: this fix aligns with ADR-0019 only on the two points its defects touch (version normalization, example pinning). Fully adopting the ADR (retiring the standalone next-tag workflow, bidirectional release coupling, the new /api/v1/appconfiguration-based runtime check) is a separate, larger migration. Keeping the next-tag workflow active for internal dev/QA testing is an already-made team decision the ADR itself anticipates, not a new deviation.
…reen note ADR-0019's Implementation Notes literally say to pin an exact date version on every example, but its own "How this plays with Evergreen" section says "latest" and "the version matching my CMS" converge for Evergreen customers by construction. main's four examples target that Evergreen audience, and an exact pin set once would itself go stale relative to Evergreen's ~2-week cadence -- recreating the staleness problem "latest" avoids. Resolves this as a deliberate, narrow divergence from the ADR's literal note (documented explicitly, not silent), scoped only to main -- the LTS-branch example copies still follow the literal exact-pin note without exception, since they exist to demonstrate against a fixed, non-Evergreen server. Adds a documentation requirement: main's four example READMEs must tell a non-Evergreen customer to manually pin the version matching their own dotCMS instance. CI guardrail and AC-004/AC-007 restored to be branch-aware (latest allowed only on main).
…cies gap Scripted inspection of every core-web/libs/sdk/*/package.json found the hardcoded "latest" in all seven (analytics, angular, client, experiments, react, uve, vue), not only the three originally suspected (react, angular, experiments) -- and in devDependencies (@dotcms/types) on all seven, a field the publish pipeline's rewrite loop never touches. Confirmed live: @dotcms/react's currently-published version still carries a literal, unmasked "latest" in devDependencies today. Settles the placeholder question: use "0.0.0", not "workspace:*" -- these libs aren't real pnpm workspace members (no pnpm-workspace.yaml exists), so an unconverted "workspace:*" leaking into a publish would be a harder failure for a customer than today's "latest". "0.0.0" is valid semver, inert without any workspace machinery, and fails loudly if the pipeline's rewrite is ever skipped. Extends deploy-javascript-sdk/action.yml's rewrite loop and the CI guardrail to cover devDependencies alongside dependencies/peerDependencies.
…there only react, angular, vue, and analytics declare @dotcms/client/@dotcms/uve as regular dependencies, which is what actually lets yarn/pnpm install a second, independently-resolved copy -- the value fix alone (e.g. "0.0.0") doesn't stop that, since a `dependency` is always resolved on its own regardless of its version string. Moving them to peerDependencies (the shape experiments already uses, and the same pattern react-dom uses for react) makes them defer to whatever the consumer already installed. Narrows the "0.0.0" placeholder decision to peerDependencies only, per developer direction: dependencies/devDependencies keep "latest" in source unchanged, since they're masked by the publish-time rewrite and customers never build from source anyway -- changing their value buys nothing. peerDependencies is different because "latest" isn't a valid semver range, so a local peer-dependency-satisfaction check (the actual pain point during dotCMS's own pre-publish testing) can't evaluate it sanely regardless of what's actually installed. Flags the real behavior-change cost: yarn classic (1.x) doesn't auto-install peer dependencies, so a customer installing e.g. @dotcms/react alone (relying on @dotcms/client coming along automatically, as it does today) will need to explicitly add it after this fix -- must be documented prominently, not silently shipped. Updates CI guardrail and ACs (new AC-003b) to match: peerDependencies must be real semver, dependencies must never contain @dotcms/client/@dotcms/uve again (regression guard), and dependencies/devDependencies "latest" is explicitly not flagged.
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
3 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.
…ddressing malformed version strings and floating dist-tags in published packages and example apps.
Proposed Changes
Checklist
Additional Info
** any additional useful context or info **
Screenshots