Versioning

The @chart-on/* packages follow semantic versioning and are released together. This page covers what a version number tells you and how to keep an app on compatible versions:

• What a version promises: which releases can break your code.
• One version for every package: why the packages move in lockstep.
• Depending on charton: the ranges to put in package.json, for apps and for plugins.
• Upgrading: where each release's changes are described.

What a version promises

A version is major.minor.patch. While charton is before 1.0, the minor number does the job the major number does later:

Release	Before 1.0 (0.3.1 to …)	From 1.0 (1.3.1 to …)
Patch	0.3.2: fixes and backwards-compatible additions	1.3.2: fixes
Minor	0.4.0: may contain breaking changes	1.4.0: backwards-compatible additions
Major	1.0.0: the stable API	2.0.0: breaking changes

A breaking change is anything that can stop working code: a removed or renamed export, option, event, method, CSS class or variable; a type that no longer accepts what it did; or a changed default or behaviour that apps rely on. New optional options, exports and events are not breaking. The full rules are in the contributing guide.

Breaking changes are announced before they land. A deprecated API keeps working for at least one minor release before 1.0 (until the next major from 1.0), and development builds log one charton [deprecated] warning per API, linking to its entry on the upgrading page. Production builds log nothing.

One entry has no stability promise: @chart-on/core/internal, which exposes engine internals for tests and experiments.

One version for every package

@chart-on/core, @chart-on/ui, @chart-on/indicators, @chart-on/locales, @chart-on/ta, @chart-on/react, @chart-on/vue and @chart-on/svelte always share one version. A release bumps all of them, even the ones whose code did not change, so the rule for staying compatible is simple: install the same version of every @chart-on/* package you use.

The packages that build on core declare it as a peer dependency (@chart-on/ui, the indicators, the locale packs and the framework wrappers), so your app has a single copy of the engine. A mismatch shows up as a peer dependency warning at install time.

To move every package to the newest release at once:

pnpm update --latest "@chart-on/*"
# or: npm install @chart-on/core@latest @chart-on/ui@latest

Depending on charton

Apps

Package managers write a caret range by default ("@chart-on/core": "^0.3.1"), and it is the right choice before and after 1.0. A caret range never crosses the release that may break:

Range	Accepts	Excludes
^0.3.1	0.3.1 to 0.3.x	0.4.0, which may break
^1.3.1	1.3.1 to 1.x.x	2.0.0

So pnpm update without --latest takes fixes and additions only, and moving to a release that may break is a deliberate edit of the range. Use the same range for every @chart-on/* package.

Plugins and packages that build on charton

A plugin declares the core versions it works with in its requires range, which chart.install checks against the running core's CORE_VERSION, and lists @chart-on/core as a peer dependency rather than a dependency, so the app's copy is used. Use a caret range from the oldest version you tested:

export const myPlugin: ChartPlugin = {
  name: 'my-plugin',
  version: '1.0.0',
  requires: '^0.3.0', // core 0.3.x
  install(ctx) {
    // ctx.registerIndicator(…), ctx.attachPrimitive(…)
  },
};

{
  "peerDependencies": { "@chart-on/core": "^0.3.0" }
}

Widen the range ('^0.3.0 || ^0.4.0') once you have tested the plugin against the new release. Plugins covers the rest of the plugin contract.

Upgrading

Every release is described in three places:

• CHANGELOG.md: one line per change, naming the package, grouped by release.
• Upgrading: the deprecated APIs with their replacements, and for each release that changes the public API the code to change, with before and after examples.
• GitHub releases: one per version, tagged v0.3.1, with that version's changelog.

To upgrade across several releases, read the upgrading page from your current version up, and fix the charton [deprecated] warnings your development build logs before moving to the release that removes them.