Upgrading GridCraft

How versions work here, what counts as a breaking change, and what to do after an upgrade. The current release is 1.0.0.

How to upgrade

# Both packages move together and are always on the same version.
npm install @gridcraft/angular@latest @gridcraft/enterprise@latest

# Pin them together too — a mixed pair is not a supported combination.
"@gridcraft/angular":    "1.0.0",
"@gridcraft/enterprise": "1.0.0"

The two packages are released together and always carry the same version. A mixed pair — say 1.0.0 of one and 1.1.0 of the other — is not a combination we build or support, and @gridcraft/enterprise declares a peer dependency that will tell you so at install time.

What the version number means

From 1.0.0, ordinary semantic versioning, with no asterisk: a minor release cannot break you, and anything that can is a major.

Whatever the number, a breaking change is named in the changelog with what broke and what to do about it. A release that quietly changes behaviour without an entry is a bug in our process, and worth reporting as one.

What we consider breaking

• Removing or renaming anything exported from @gridcraft/angular.
• Changing the shape of GridConfig, GridColumn, GridDataSource, FetchParams or FetchResult in a way that makes existing code fail to compile.
• Changing what an existing config value does, including defaults.
• Moving a feature between the free and paid tiers.
• Raising the minimum Angular version.
• Changing the shape of a saved state snapshot such that an old one no longer restores.

What we do not consider breaking

• CSS class names and DOM structure. These are not API. Styling the grid through --gc-* custom properties is supported and stable; a selector reaching into .gc-body__inner is not, and may move in a patch.
• Console message wording. The condition a warning describes is stable; its exact sentence is not. Do not assert on message text in tests.
• Anything under @gridcraft/angular/internal. It is importable because the two packages need a shared module specifier, not because it is for you. It changes without notice.
• Bundle size and internal file layout. Measured and published, not promised.

Pinning

A caret range is safe from 1.0 on — ^1.0.0 takes 1.1 and 1.9 and stops before 2.0, which is exactly the boundary the table above draws. Pin the exact version instead if you would rather read every minor's changelog before taking it. The one rule either way: the two packages carry the same range.

// A caret is safe from 1.0 on: it allows 1.1 and 1.9, and stops before 2.0.
"@gridcraft/angular":    "^1.0.0",
"@gridcraft/enterprise": "^1.0.0"

// Pin exactly if you would rather read every minor's changelog before taking it:
"@gridcraft/angular":    "1.0.0",
"@gridcraft/enterprise": "1.0.0"

// Whichever you choose, keep the two ranges identical.

After you upgrade

# The three checks worth running after any grid upgrade, in this order:
ng build                 # template type errors surface here first
npm test                 # your data source + column specs
npx playwright test      # the one that catches a silent behaviour change

The order matters. A template type error appears at build time and is cheap to fix. A behaviour change that still compiles is the expensive one, and only an end-to-end test that asserts on data — rows reordered, rows filtered, a total recalculated — will find it. See Testing the Grid.

Also worth a look after any upgrade: your browser console on a page with a grid, in a development build. Newly-unsupported feature combinations announce themselves there, and Dev-time Validation explains what you are reading.

Skipping versions

Upgrading across several releases at once is supported — there are no ordered migration steps to run. Read every changelog entry between your version and the target, not just the newest one: the breaking change you need to know about is usually in the middle.

Angular upgrades

Upgrading Angular and upgrading the grid are separate jobs; do them one at a time. Our supported range is published and verified on Angular Compatibility. If your target Angular is outside it, the install fails rather than the build — which is the outcome you want, and the reason to upgrade the grid first.