Versioning

What it is

A kit version is a contract: a fixed rule for what its next release is allowed to change out from under your workspace, and how long you have before you must respond to a release that changes it anyway. Your workspace declares the kit line it is holding to as a dependency range:

"dependencies": {
  "@homepages/template-kit": "^2.0.0"
}

The workspace scaffolder (npm create @homepages/workspace) writes that range for you, naming the kit line you scaffolded on. The caret means >=2.0.0 <3.0.0: every feature and fix on that major reaches you automatically, and the next major never does without you asking.

Why it works this way

The kit, the CLI and the lint preset are three separate packages because three different things install them for three different reasons. The kit is a set of React primitives your templates import, so it is a runtime dependency and ends up in the production install of every app that renders a template. The lint preset wants ESLint and a parser and no React at all, and the CLI is a command you run — both are dev dependencies. Merging them into one package would pull each one’s dependency tree into the others’ installs. See the ESLint preset for that split described from the preset’s side.

They share one version number even so, and that is a separate decision from the packaging one. Three numbers moving on their own cadences would make every combination of them a pairing somebody has to reason about — which CLI works with which kit, which preset understands which rules — and there is no answer to that question a version number alone can carry. One number answers it by construction: every release publishes all of them at that number, so packages that share it were built, tested and shipped together.

The caret exists so that taking a major is something you schedule rather than something that lands on you. A patch or a minor reaches you automatically because neither can take anything away; a major cannot reach you at all until you ask for it by name. What sets the schedule is the platform rather than the release: submissions are judged against the kit major the registry itself is on, so a new major is yours to take on your own time up until the registry adopts it.

How it works

Three kinds of release

The kit reads semver the standard way.

Patch (2.1.0 → 2.1.1) — fixes. Your caret already allows it, so it reaches you on its own: the next author command you run brings the workspace up to date first and then does what you asked. Staying current is that behaviour in full.

Minor (2.1.x → 2.2.0) — new, and backward compatible. A minor adds; it never takes away. Nothing you have already authored stops working, so a minor arrives exactly the way a patch does, and there is nothing to migrate.

Major (2.x → 3.0.0) — breaking. A major is the only release that changes something you author against. Your caret will not carry you across one, and nothing moves you across one without your say-so. That is the caret doing its job.

To take it, ask for it:

template-kit upgrade
npm run check

check is your migration list — it reports what the new version rejects. Read the CHANGELOG in the package (node_modules/@homepages/template-kit/CHANGELOG.md) for what changed and why.

The CLI and the lint preset carry the same number

@homepages/template-cli (which provides the template-kit command) and @homepages/eslint-plugin-template (the lint preset) are separate packages released at the kit’s own number, so a kit at 2.4.0 has a 2.4.0 CLI and a 2.4.0 preset alongside it.

They move as a set rather than one at a time. Both declare the kit as a peer dependency covering its whole major, so a package moved on its own across a major is exactly what produces an unmet peer — which is why template-kit upgrade rewrites every @homepages/* range in your package.json together and installs once, and why inside a major the update that happens on its own covers all of them at the same time.

How long you have

Submissions are accepted against the registry’s current kit major, and only that major. The platform rebuilds every submitted template on the kit it is pinned to, so a pack built on any other major is refused at submission rather than left to fail that rebuild.

A minor never puts you out of range, and neither does a patch: any 2.x pack submits against a registry on any other 2.x.

Neither direction is tolerated. A pack built on a major the platform has not adopted yet is refused, and so is one built on a major it has moved past. Take a new major when it lands, and expect to submit against it once the platform is on it.

template-kit pack still succeeds on an out-of-range major — packing is a local build and knows nothing about the registry’s pin. The refusal comes at submission, and it names the exact range to set.

Checking where you are

npm ls @homepages/template-kit    # what you have installed
npm view @homepages/template-kit version   # the current release

The same two commands work for @homepages/template-cli and @homepages/eslint-plugin-template. template-kit --version prints the pair the command is actually running as <cli> (kit <kit>) — see the CLI reference for the rest of its commands.

What it is not

check is not a migration tool. Calling it your migration list means it tells you what the new version rejects, one finding at a time. It has no --fix, it rewrites nothing, and there is no codemod behind it — the edits are yours to make. What it gives you is a finite, ordered list and a green run to aim at.

A major is not something that happens to you. Your caret will not carry you across one, and neither will the update the CLI runs on its own: a major arrives in your workspace when you answer yes to the question it asks, or when you run template-kit upgrade, and not before. That is why a breaking kit release is a scheduling question rather than an incident.

A shared number is not a claim about what you have. The family being released together says what the packages on 2.4.0 were built against — not which of them your workspace resolves today. The number in your @homepages/template-kit dependency describes the authoring contract you write against; template-kit --version prints the pair actually running your check, and the two disagreeing is a workspace to reinstall rather than a version to reason about.

Where next

• Staying current — what the CLI updates on its own before a command, what it asks about first, and how to switch it off.
• Run check — the run that becomes your migration list.
• template-kit pack — the submission zip, which is produced only when check is green.
• ESLint preset — the preset’s own setup and scope.