Versioning and migrations
How versions are numbered, how to read the CHANGELOG and what to do before and after upgrading. The full policy and what is supported is in Support; this is the practical part.
#How versions are numbered
Semantic versioning is followed (major.minor.patch):
| Change | Example | What to expect |
|---|---|---|
| Patch | 1.0.0 → 1.0.1 | Fixes only. Upgrading is safe |
| Minor | 1.0.x → 1.1.0 | It only adds. (Up to 0.x, a minor could break) |
| Major | 1.x → 2.0 | May break. Whatever is removed was announced as deprecated a minor version earlier |
What counts as "breaking" (removing or renaming a public export, changing what a function returns, changing a default value that alters the result, or raising a browser minimum) is in Support.
#How to read the CHANGELOG
Each version in the CHANGELOG (in Spanish) is divided into sections, always in this order:
- Breaking changes ("Cambios que rompen"): what to check before upgrading, each with how to migrate. If the section doesn't exist, that version breaks nothing.
- Added ("Agregado") and Changed ("Cambiado"): new features and behavior adjustments.
- Deprecated ("Obsoleto"): what will be removed later and what to replace it with.
- Fixed ("Corregido"): bugs and security.
#Before upgrading
- Choose how to pin the version. From
1.0you can use"nexus-dialogs": "^1.0.0": minor versions and patches do not break. If you prefer that a fresh install never changes on its own, use the exact version, without^or~. - Read "Breaking changes" for every version between yours and the new one, not just the latest.
- Search your code for what each change mentions (the function or option name).
- Check the types:
tscflags removed or renamed exports and options that changed shape. - Upgrade and run your tests. If you have UI tests, dialogs are native
<dialog>elements withdata-nexus-dialog, so your selectors should not change.
#What is watched so it doesn't break you
npm run api:checkfails if the public API changes without updating its report, so a change in the exports never goes unnoticed.test/tipos/contratos.tspins what each function returns (Contracts).- Each version is tested in Chromium, Firefox and WebKit, and the published package is installed and used from Node, Vite and webpack before release.
#Known migrations
| From | To | What changes | How to migrate |
|---|---|---|---|
0.5.x | 1.0.0 | Nothing breaks: 1.0.0 only fixes the public API and semantic versioning | Upgrade and run your tests |
0.4.x | 0.5.0 | strictHtml is true by default: string html is shown as text | With your own content, configure({ strictHtml: false }). With outside content, configure({ sanitize: (h) => DOMPurify.sanitize(h) }). Nodes and plain texts don't change |
New migrations are added here as they come out. For coming from SweetAlert2 there is a separate guide: Migrate from SweetAlert2.
#When something is going to be removed
A function that is going to be retired keeps working for one full minor version, marked @deprecated in the types (your editor strikes it through) and listed under "Deprecated" in the CHANGELOG with its replacement. It is only removed in the next major version. (In 0.x the notice could last less, but it always appeared under "Breaking changes".)
#If the upgrade breaks something
Go back to the previous version (npm install nexus-dialogs@1.0.0) and open an issue with the version you come from, the one you are going to and a minimal case. If the change was not in "Breaking changes", it is a CHANGELOG error and it gets fixed.