diff --git a/_data/docs-home.yml b/_data/docs-home.yml index aa3b2e839d..c5d4b19b94 100644 --- a/_data/docs-home.yml +++ b/_data/docs-home.yml @@ -374,7 +374,11 @@ toc: path: /docs/user-guide/contribution/ui/advanced-development/ - title: Troubleshooting path: /docs/user-guide/troubleshooting/ -- title: Release notes - path: /docs/reference/releases/ -- title: Roadmap - path: /docs/reference/roadmap/ +- title: Releases + section: + - title: Versioning and Release Policy + path: /docs/reference/release-policy/ + - title: Release notes + path: /docs/reference/releases/ + - title: Roadmap + path: /docs/reference/roadmap/ diff --git a/_data/pages_info.yml b/_data/pages_info.yml index aa7c90291d..b8133a3394 100644 --- a/_data/pages_info.yml +++ b/_data/pages_info.yml @@ -4031,6 +4031,9 @@ "/docs/reference/python-rest-client/": url: "/docs/reference/python-rest-client/" redirect_from: [] +"/docs/reference/release-policy/": + url: "/docs/reference/release-policy/" + redirect_from: [] "/docs/reference/releases/": url: "/docs/reference/releases/" redirect_from: [] @@ -5012,6 +5015,9 @@ "/docs/user-guide/rule-engine-2-0/nodes/action/device-state/": url: "/docs/user-guide/rule-engine-2-0/nodes/action/device-state/" redirect_from: [] +"/docs/user-guide/rule-engine-2-0/nodes/action/generate-dashboard-report/": + url: "/docs/user-guide/rule-engine-2-0/nodes/action/generate-dashboard-report/" + redirect_from: [] "/docs/user-guide/rule-engine-2-0/nodes/action/generate-report/": url: "/docs/user-guide/rule-engine-2-0/nodes/action/generate-report/" redirect_from: [] diff --git a/_data/pe/docs-home.yml b/_data/pe/docs-home.yml index 6584e1453e..aa30769e6d 100644 --- a/_data/pe/docs-home.yml +++ b/_data/pe/docs-home.yml @@ -392,7 +392,11 @@ toc: path: /docs/pe/user-guide/contribution/ui/advanced-development/ - title: Troubleshooting path: /docs/pe/user-guide/troubleshooting/ -- title: Release notes - path: /docs/pe/reference/releases/ -- title: Roadmap - path: /docs/pe/reference/roadmap/ +- title: Releases + section: + - title: Versioning and Release Policy + path: /docs/reference/release-policy/ + - title: Release notes + path: /docs/pe/reference/releases/ + - title: Roadmap + path: /docs/pe/reference/roadmap/ diff --git a/_sass/_docs.sass b/_sass/_docs.sass index 934a780aaf..7bf1eb4fcd 100644 --- a/_sass/_docs.sass +++ b/_sass/_docs.sass @@ -408,6 +408,14 @@ @media screen and (min-width: 1500px) width: calc( 100% - 810px) + span.code-light + font-family: ui-monospace, SFMono-Regular, Menlo, Consolas, monospace + border: 1px solid rgba(0, 0, 0, 0.05) + background: rgba(42,125,236,0.08) + padding: 0.2em + border-radius: 4px + color: inherit + #docsToc position: fixed background-color: #F9F9F9 diff --git a/docs/reference/release-policy.md b/docs/reference/release-policy.md new file mode 100644 index 0000000000..5dbfd07552 --- /dev/null +++ b/docs/reference/release-policy.md @@ -0,0 +1,137 @@ +--- +layout: docwithnav +title: Versioning and Release Policy + +--- + +* TOC +{:toc} + +This guide explains how ThingsBoard versions are numbered, how long each version is supported, what kind of upgrade requires downtime, and which Docker tags to use in different environments. +It’s written for platform administrators, SREs, DevOps engineers, and technical users who deploy and maintain ThingsBoard. + +--- +## Thingsboard versioning +ThingsBoard version numbers reflect the scope of changes introduced in each release. This follows semantic versioning principles, helping you gauge the potential impact of upgrading. +Thingsboard version numbers have four parts: MAJOR.MINOR.MAINTENANCE.PATCH. For example, version 4.2.1.0 indicates major version 4, minor version 2, maintenece 1 and patch level 0. + +The version number is incremented based on the level of change included in the release. + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
LevelChangesUpgrade scripts required
MAJORBreaking changes, removed/deprecated APIs, major migrations, new featuresYes
MINORNew features with backward compatibilityYes
MAINTENANCEBug fixes/security vulnerabilities/framework upgrades that may require upgrade scriptsYes
PATCHHotfix releases that do not require upgrade scripts (critical bugs/security fixes; no env/DB changes).No
+ +**Examples** + +4.2.0.0 — Initial 4.2 LTS release + +4.2.0.2 — Two hotfixes later, no upgrade scripts required to move within 4.2.0.x + +4.2.1.0 — First maintenance release; expect upgrade scripts + +4.2.1.3 — Hotfixes on top of 4.2.1.0; zero‑downtime within 4.2.1.x + + +## Lifecycle & Support (How long versions are supported) + +ThingsBoard maintains **Long‑Term Support (LTS)** lines for production users. Customers using LTS releases can be confident that their critical systems will be protected and operate reliably. + +* **LTS declaration:** We announce a new **LTS** line each year; each LTS line is supported for **18 months** from initial LTS GA (e.g., from 4.2.0.0 release date) + + Active support includes: + - Bug fixes, security patches + - New MAINTENANCE (…x.0) and PATCH (…x.y) releases as needed + +* **Major releases:** When breaking changes are introduced. + +* **Minor releases:** Typically every **three** months. + +* **Maintenance releases:** When bug fixes need an upgrade script. + +* **Patch releases:** When bug fixes don`t need an upgrade script. + +## Choosing the Right Version + +**If you run production:** + +1. **Prefer the latest LTS line** in Active Support. + +2. To stay up to date with hotfixes, track the line’s PATCH updates only (same MAINTENANCE number, e.g., 4.2.1.0 → 4.2.1.3). + +3. **Schedule maintenance windows** to adopt new **MAINTENANCE** releases when needed (e.g., 4.2.0.x → 4.2.1.0). + + +## Docker Hub Tagging Strategy + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
TagExamplePurposeUpdate Policy
M.m.P.p4.2.1.0ProductionImmutable
M.m.P4.2.1-latestAutomatic safe patches Floating (within 4.2.1.x)
latestlatestFor development/testing (non-LTS)Floating (latest master release)
+ +**Recommendations** + + - **Production:** Pin to the immutable full tag (e.g., 4.2.1.0). You update only when you change the tag. + + - **Auto security hotfixes (no downtime):** Use 4.2.1.1, 4.2.1.2, … , but never jump to 4.2.2.0. + + - **Avoid latest in production.** It may include breaking changes and is not covered by the LTS policy. + +## Compatibility & Deprecations + + - **API/behavior compatibility** is maintained within a MAJOR version whenever feasible. Minor releases may deprecate features but should not break existing integrations without a migration path. + + - **Deprecation policy:** Features flagged as deprecated in a Minor release will remain for at least one subsequent Minor before removal (or be guarded by feature flags when possible). Deprecations and removals are always called out in Release Notes. \ No newline at end of file