SDK versioning & release-alignment initiative (ADR-0019) — tracking

[KevinDavilaDotCMS]

Description

Umbrella/tracking task for the multi-phase effort to align @dotcms/* SDK package versioning
and publishing with dotCMS's own date-lockstep release versioning
(ADR-0019),
and to give both dotCMS and SDK consumers a reliable way to detect and manage SDK-compatibility
breaks across releases.

Before this initiative, SDK packages versioned independently (SemVer, with a continuous @next
prerelease channel), had no way to signal a compatibility floor to installed clients, and had no
structured process for keeping that floor accurate over time. Each phase below closes one part of
that gap. This issue exists purely for tracking/visibility — sub-tickets are linked as they're
created, no new work is scoped directly on this issue itself.

Completed phases

• Align SDK publish pipeline with dotCMS date-lockstep versioning #36587 — Align SDK publish pipeline with dotCMS date-lockstep versioning (PR refactor(deployment): update SDK publishing workflow to align with dotCMS release strategy #36633,
  merged)
  SDK version = dotCMS release version, always. Removed independent SemVer and the continuous
  @next prerelease channel. Publishing is triggered only by a real dotCMS release
  (release: created), mirroring the existing dotCLI publish mechanism — every @dotcms/*
  package publishes to latest at the exact release version, including releases with no SDK code
  changes.

• SDK compatibility handshake: server advertises version + minimum supported SDK, SDKs warn on mismatch #36609 — SDK compatibility handshake (PR feat(sdk): Implement SDK compatibility handshake server advertises version + minimum supported SDK, SDKs warn on mismatch #36678, merged)
  The server advertises its own version and a manually-maintained compatibility floor
  (MinSdkVersion.VALUE) via two response headers (X-DotCMS-Version, X-DotCMS-Min-SDK),
  implemented as a WebInterceptor so it covers both REST and GraphQL/plain-servlet traffic.
  @dotcms/client reads these off responses it already makes and warns (console.error if the
  installed SDK is older than the floor, console.warn if newer than the server) — fails open,
  once per session.

• Reintroduce next npm dist-tag for internal dev/QA testing on merge to main #36701 — Reintroduce a next npm dist-tag for internal dev/QA (PR chore(sdk): Bring back 'next' tag publish on sdks #36722, merged)
  Internal-only next tag, published automatically on every merge to main that touches SDK
  files, computed as <current latest>-next.<run_number>. Kept fully isolated from the
  date-lockstep latest publish flow (its own trunk-only job, never part of the release
  pipeline) so it can't reopen the "second door for off-version publish" risk the original ADR
  eliminated.

• Automate MIN_SDK_VERSION bump via release pipeline + AI-based SDK-breaking-change detection #36698 — Automate MinSdkVersion.VALUE maintenance via the release pipeline + AI-based
  breaking-change detection (PR feat(workflows): Add Claude AI SDK breaking change check workflow #36728, merged)
  Replaces the manual "developer edits the constant in their PR" procedure from SDK compatibility handshake: server advertises version + minimum supported SDK, SDKs warn on mismatch #36609 with a
  release-pipeline-driven mechanism: an AI check (ai_claude-sdk-breaking-change.yml) labels PRs
  that break SDK compatibility against a new reference doc
  (docs/core/SDK_BREAKING_CHANGE_CATEGORIES.md); a new bump_min_sdk_version release input,
  validated at release time (the release fails outright if a labeled PR is in range and the
  input was left unset); and a post-release job that — only once the release has fully
  succeeded — opens a PR bumping the constant and pings Slack for human review. Never a direct
  push to main; nothing changes if the release fails partway through.

Known follow-up, not yet ticketed

• SDK/CLI npm publish currently fires on release: created, which happens very early in
  cicd_6-release.yml (inside release-prepare, as soon as the GitHub Release object is
  created) — well before build/deployment/release actually confirm the dotCMS release
  succeeded. Observed in practice: a real release run where the later phases failed, but the SDK
  packages had already published to npm. Proposed fix: create the GitHub Release as a draft in
  release-prepare (the git tag itself is unaffected by draft status, so build can still check
  it out), switch cicd_release-sdk.yml and cicd_release-cli.yml to trigger on
  release: published instead of release: created, and add a final step to cicd_6-release.yml
  (after build, deployment, release, and release-notes all succeed) that flips the release
  from draft to published — which is what would actually trigger the SDK/CLI publish. Affects both
  SDK and CLI publish, since both currently share the same created trigger. Needs its own ticket
  before work starts.

Priority

High

Additional Context

Each phase above was implemented, reviewed, and tested independently (including dry-runs in a
disposable fork, dotCMS/core-workflow-test, before touching this repo) — see each linked PR's
description and review-comment history for the detailed design decisions and edge cases considered
for that phase. This issue is a pure tracking/index task; sub-tickets get added here as they're
created.

[github-actions]

PRs linked to this issue

• Added jsdoc to random function in order to trigger a new next sdk ver… by @KevinDavilaDotCMS
• Little change on comments to trigger sdk publication pipeline by @KevinDavilaDotCMS
• chore(sdk): bump MinSdkVersion.VALUE to 26.07.28-01 by @dotCMS-Machine-User