cms-lab
Docs / Versioning

Versioning and stability

cms-lab is public and usable, but it is still early. The project keeps command behavior, config shape, and adapter maturity explicit so teams can decide how much trust to put behind a scan.

Current status

The CLI is best treated as a local pre-deploy check for projects that can provide a clear CMS-to-route mapping. It is not a replacement for unit tests, Playwright, Lighthouse, axe, CMS permissions, or production monitoring.

No hosted dependencyThe scan runs inside your project and reads only the CMS endpoints and site URLs you configure. Reports are local files unless you choose to upload them in CI.

What should stay stable

  • Core commands: init, doctor, scan, agent-context, and explain.
  • Common scan outputs: terminal, JSON, Markdown, JUnit, Slack summaries, and local HTML reports.
  • Diagnostic severity names: error, warning, and info.
  • The main config entry point: defineConfig from @cms-lab/core.

What may still change

Minor releases can refine adapter options, generated init templates, report layout, diagnostic wording, and docs examples. Any breaking change to command names, config keys, or JSON output should ship in a major release unless the existing behavior is broken or unsafe.

Deprecations should be announced in the changelog first. When practical, the CLI should warn before removing an option.

Adapter maturity

CMS adapters do not all have the same coverage. Check the public matrix before treating an adapter as a deploy gate for a new project.

Open the tested-with matrix

How to adopt safely

  1. Run locally with a small route set first.
  2. Add --fail-on neverin CI until the first report matches your team's expectations.
  3. Pin the package version in production projects.
  4. Review generated reports before turning warnings into failures.
  5. Keep secrets in environment variables and do not commit generated reports with private CMS data.
npx @cms-lab/cli scan --ci --report --fail-on never

Release notes

Every public release should be reflected in the changelog and GitHub Releases. Patch releases should be safe bug fixes or docs updates. Minor releases can add adapters, output formats, commands, or checks. Major releases are for intentional breaking changes.

Read the changelog and GitHub Releases.