Skip to content

docs: point CLI compatibility manifest to CLI repo#333

Merged
pkosiec merged 9 commits into
mainfrom
pkosiec/appkit-version-pinning
May 12, 2026
Merged

docs: point CLI compatibility manifest to CLI repo#333
pkosiec merged 9 commits into
mainfrom
pkosiec/appkit-version-pinning

Conversation

@pkosiec
Copy link
Copy Markdown
Member

@pkosiec pkosiec commented Apr 30, 2026 •
edited
Loading

Summary

Points CONTRIBUTING.md to the CLI compatibility manifest in the CLI repository and removes the local copy (manifest, validator, tests, CI step, bump skill).

Companion PR: databricks/cli#5139

@pkosiec pkosiec force-pushed the pkosiec/appkit-version-pinning branch 3 times, most recently from 8d8dc43 to 9b43085 Compare April 30, 2026 16:12
@pkosiec pkosiec marked this pull request as ready for review April 30, 2026 16:12
@pkosiec pkosiec mentioned this pull request Apr 30, 2026
Merged
@pkosiec pkosiec requested a review from a team as a code owner May 5, 2026 12:36
@pkosiec pkosiec requested a review from calvarjorge May 5, 2026 12:36
@pkosiec pkosiec changed the title feat: add CLI compatibility manifest for template version pinning feat: add CLI compatibility manifest for version pinning May 5, 2026
@pkosiec pkosiec force-pushed the pkosiec/appkit-version-pinning branch from 05c899d to f42b850 Compare May 5, 2026 12:42
@pkosiec pkosiec changed the title feat: add CLI compatibility manifest for version pinning docs: point CLI compatibility manifest to CLI repo May 5, 2026
@pkosiec pkosiec mentioned this pull request May 5, 2026
Merged
@MarioCadenas
Copy link
Copy Markdown
Collaborator

MarioCadenas commented May 5, 2026

we should wait to merge this until the CLI pr is merged just in case something changes

@pkosiec
Copy link
Copy Markdown
Member Author

pkosiec commented May 6, 2026

Yes, absolutely, this PR will wait until the related one is merged 👍

pkosiec added 9 commits May 12, 2026 16:35
@pkosiec
feat: add CLI compatibility manifest for template version pinning
ac66c1e 
Add cli-compat.json that maps CLI versions to compatible AppKit template
and Agent Skills versions. This enables decoupling template delivery from
CLI release cycles — older CLI versions automatically receive a compatible
template version.

Also add tools/check-cli-compat.ts validation script and CI step to
prevent malformed manifests from being merged.

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
fix: add next>=max validation and document check-cli-compat tool
ea6976f 
- Validate that "next" appkit/skills versions are >= all versioned
  entries to prevent accidental downgrades for newest CLIs
- Add check-cli-compat.ts to CLAUDE.md tools listing

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
fix: tighten cli-compat.json validation
6b0f389 
- Reject prerelease suffixes in SEMVER regex (compareSemver
  produces NaN for them, silently bypassing next>=max check)
- Check appkit and skills fields independently in next>=max
  validation (previously a missing appkit skipped skills too)
- Require at least one versioned CLI entry besides "next"

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
docs: document CLI compat manifest and simplify initial entries
74af1fa 
- Add "Updating the CLI compatibility manifest" section to CONTRIBUTING.md
- Reduce cli-compat.json to two initial entries (next + 0.299.0)

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
fix: tighten cli-compat validator and add unit tests
0c287f7 
- Bail out of cross-entry comparison when structure validation fails,
  preventing NaN-based semver comparisons on invalid entries
- Reject unexpected fields in manifest entries
- Validate versioned keys are in ascending semver order
- Extract validateCliCompat() for testability
- Add 20 unit tests covering all validation branches

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
docs: align CLI compat update docs with design doc and add bump skill
4251772 
- Rewrite "When to update" section in CONTRIBUTING.md to match design doc
  (evals step, "last 3 CLI versions" detail, future automation note)
- Add bump-cli-compat Claude Code skill for updating the manifest

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
docs: document CLI resolution fallback for older versions
c6d5eaf 
Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
refactor: move cli-compat manifest to CLI repo
fa04e73 
The cli-compat.json manifest, validator, tests, CI step, and bump
skill have been moved to the CLI repository (databricks/cli). This
simplifies the architecture by colocating the manifest with its
consumer.

CONTRIBUTING.md retains a brief pointer to the CLI repo.

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec
docs: document CLI version resolution in CONTRIBUTING.md
a0e73bc 
Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec pkosiec force-pushed the pkosiec/appkit-version-pinning branch from dc4ef4f to a0e73bc Compare May 12, 2026 14:35
simonfaltum pushed a commit to databricks/cli that referenced this pull request May 12, 2026
@pkosiec
Resolve AppKit and Agent Skills versions from compatibility manifest (#…
3e4cf68 
…5139)

## Summary

Introduces a CLI compatibility manifest
(`internal/build/cli-compat.json`) that maps CLI versions to compatible
AppKit template and Agent Skills versions. This enables template updates
to reach users without CLI releases.

### Manifest format

The manifest is purely range-based — each versioned entry defines a
**range floor** that applies to that CLI version and all versions above
it, up to the next entry. The manifest should be sparse: only add a new
entry when a compatibility boundary changes (e.g., new AppKit templates
require specific CLI features).

### Resolution

- **Exact match** → use that entry
- **Between entries** → nearest lower version
- **Newer than all** → highest versioned entry
- **Dev builds** (`0.0.0-dev*`) → highest versioned entry

### Manifest sources (fallback chain)

1. Fresh local cache (< 1h)
2. Remote fetch from GitHub (with retry)
3. Stale local cache or embedded manifest fallback

Set `DATABRICKS_FORCE_EMBEDDED_COMPAT=true` to skip remote fetch and use
only the embedded manifest (useful for local development).

### Companion PRs

- [databricks/appkit#333](databricks/appkit#333)
-
[databricks/databricks-agent-skills#64](databricks/databricks-agent-skills#64)

## Screenshot

<img width="1046" height="570" alt="image"
src="https://github.com/user-attachments/assets/1b51cd90-bcaa-4b0e-bcbd-a5370da572ef"
/>

---------

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
@pkosiec pkosiec merged commit 1cbf07b into main May 12, 2026
9 checks passed
@pkosiec pkosiec deleted the pkosiec/appkit-version-pinning branch May 12, 2026 16:17
pkosiec added a commit to databricks/databricks-agent-skills that referenced this pull request May 12, 2026
@pkosiec
docs: document CLI version resolution in CONTRIBUTING.md (#64)
6402677 
## Summary

Adds a "Version resolution in Databricks CLI" section to CONTRIBUTING.md
explaining that the CLI uses `cli-compat.json` to determine which Agent
Skills version to install.

Companion PRs:
- [databricks/cli#5139](databricks/cli#5139)
- [databricks/appkit#333](databricks/appkit#333)

Signed-off-by: Pawel Kosiec <pawel.kosiec@databricks.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@atilafassina atilafassina atilafassina approved these changes

@calvarjorge calvarjorge Awaiting requested review from calvarjorge calvarjorge is a code owner automatically assigned from databricks/eng-apps-devex-appkit

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

3 participants

@pkosiec @MarioCadenas @atilafassina