Release Policy

This guide explains how ThingsBoard versions are numbered, how long each version is supported, and which Docker tags to use in different environments. It is written for platform administrators, SREs, DevOps engineers, and technical users who deploy and maintain ThingsBoard.

ThingsBoard version numbers follow semantic versioning principles with four parts: MAJOR.MINOR.MAINTENANCE.PATCH (e.g., 4.2.1.0).

Level	Changes	Upgrade scripts required
MAJOR	Breaking changes, removed/deprecated APIs, major migrations, new features	Yes
MINOR	New features with backward compatibility	Yes
MAINTENANCE	Bug fixes, security fixes, framework upgrades	May be required
PATCH	Hotfix releases — critical bugs/security fixes; no environment or 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
• 4.2.2.0 — Maintenance release: includes Angular upgrade (18 → 20); no DB scripts required, but potential UI impact

ThingsBoard maintains Long-Term Support (LTS) lines for production users.

Release type	Description	Support duration	Typical frequency
LTS	Announced yearly; for stable, long-term production use	18 months from initial LTS GA date	Annually
Standard	Releases between LTS lines, including new features	6 months from initial GA date	Every three months (Minor)

1. Track PATCH updates within the same MAINTENANCE number (e.g., 4.2.1.0 → 4.2.1.3) — these are safe, zero-downtime updates.

2. Schedule maintenance windows to adopt new MAINTENANCE releases when needed (e.g., 4.2.0.x → 4.2.1.0).

3. Framework upgrades in MAINTENANCE releases (e.g., Angular 18 → 20):

   • Full backward compatibility for the core platform is maintained — no upgrade scripts required.
   • However, custom UI code (widgets or custom CSS) that depends on internal component structure or CSS variable names may break.
   • This can affect up to 1% of users with heavy customizations.
   • Recommendation: Always test custom UI in a staging environment before upgrading.

Tag	Example	Purpose	Update policy
M.m.P.p	4.2.1.0	Production	Immutable
M.m.P	4.2.1-latest	Automatic safe patches	Floating (within 4.2.1.x)
latest	latest	Development and testing only	Floating (latest master release)

Recommendations:

• Production: Pin to the immutable full tag (e.g., 4.2.1.0). You update only when you explicitly change the tag.
• Auto security hotfixes: Use the three-part tag (e.g., 4.2.1-latest) to receive 4.2.1.1, 4.2.1.2, etc. automatically, 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.

• 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 release before removal (or be guarded by feature flags when possible). Deprecations and removals are always called out in release notes.