A platform that silently changes under customers' feet loses their trust. One day a button works; the next day it's in a different place, or it behaves differently, or it's been replaced by a different affordance entirely. The customer didn't ask for the change, didn't get warned about it, and now has to figure out what happened while their users send confused support tickets. For a consumer application, that rolling-deployment style is sometimes tolerable; for a business platform where the same users do the same work every day and need their tools to behave predictably, it's corrosive. The right approach is the opposite: every tenant runs a known, named version of the platform, upgrades are controlled events with release notes and advance notification, and when something goes wrong, the rollback path is short and well-lit.
Named versions make the platform's behavior identifiable at a given point in time. Each release of the platform has a human-readable version identifier — the same kind of identifier that any serious piece of software has used for decades. When a tenant is running version X, there's a canonical answer to what "version X" means: a specific release with specific features, specific fixes, and specific release notes. Support conversations start with "what version are you on?" and have one correct answer. Issue reports reference a version; the engineering team reproducing the issue knows exactly which release to match.
Visible current version puts that information where administrators can see it. The version is shown in the administration area; platform operators see it in their fleet view; the event log references the running version at the time of each event. There's no guesswork about what code is currently running, no ambiguity about whether a recent change has been deployed yet. For the moments when a clear answer to "what version is active here" matters — which is most moments, once you've experienced an environment where the answer is unclear — the information is visible to the people who need it.
Release notes per version turn each release into a narrative artifact rather than a mystery. Every version ships with release notes that describe what's new, what's fixed, and what's changed — at a level of detail that matters to users and administrators rather than developers. A tenant admin reading the release notes for the upcoming version can prepare their users for what they'll see. A customer evaluating the platform can review the release cadence and the substance of each release. An auditor can tie observed behavior changes to documented releases. Release notes are first-class: not an afterthought, not a generated changelog, but a crafted summary that explains the release to humans.
Staged rollouts let operators upgrade tenants in groups rather than all at once. A new release can go first to an operator's own internal test tenant, then to a small group of early-adopter customer tenants, then to the broader population. At each stage, any issues surface on a small footprint before affecting everyone. For operators managing larger fleets, this staged approach is what makes the upgrade process genuinely safe: the new version is proven in limited deployment before it's universal, and the operator decides the pace.
Rollback window handles the case where a new version turns out to cause a problem that wasn't caught during staging. For a defined window after each upgrade — measured in days rather than minutes — the rollback is a supported operation. An affected tenant can be reverted to the previous version; any data written during the period since the upgrade is preserved; the tenant returns to known-good behavior while the issue is investigated and addressed. That reversibility is what separates a confident deployment process from a nerve-wracking one.
Upgrade notifications keep tenants informed before and after each change. Before an upgrade, tenant admins see a notification describing what's coming and when; after an upgrade, they see confirmation of what was applied. Users who are signed in at the moment of an upgrade may see a gentle prompt to refresh; background work in progress is preserved across the upgrade where possible. The experience is meant to be the opposite of a surprise: the upgrade happens on an announced schedule, with visibility into what changed, and most users notice only that the release notes they were looking forward to are now active.
Compatibility guarantees are the engineering commitment that makes versioning trustworthy at scale. The REST API, the internal script environment, the data model, the expression language — all of these carry backward-compatibility expectations across releases. A script that works on version X is expected to work on version X+1. An API integration that was built against last year's release continues to work this year. Breaking changes are handled with deprecation periods rather than overnight swaps. For the stability-sensitive contexts where compatibility is genuinely important — external integrations, long-lived automations, custom code — those guarantees are what let the platform evolve without forcing customers to re-implement against every release.
Deprecation signals tell customers what's going away before it goes away. A feature slated for removal is flagged in release notes and in the administration interface; automations or scripts referencing it receive warnings; the documentation marks the feature with its sunset date. Customers with sufficient notice can plan their migration off the deprecated feature; customers with insufficient notice can't. We choose to give generous notice — measured in months or longer for anything meaningful — because rushed migrations are how customer trust erodes.
Maintenance windows let operators schedule upgrades to avoid the hours when their customers most need the platform available. A tenant serving retail operations might prefer upgrades on Sunday nights; a tenant serving financial operations might prefer upgrades outside of month-end close; a tenant with a global user base might have no "good" time and prefer to be upgraded during the quietest window in their specific rotation. The maintenance window is configurable per tenant, and upgrades respect the configuration where they can.
For platform operators, version management is the feature that turns release engineering from a high-anxiety activity into a routine operational practice. For tenant administrators, it's the feature that gives them predictable control over when and how their tenant's behavior changes. For end users, the surface-level experience is the simplest possible: things work today the way they worked yesterday, and when they change, the change was announced and explained. For the adjacent topics, the multi-tenancy article covers the fleet architecture that staged rollouts apply to, the event log article covers the version-stamped audit trail, and the platform changelog is where the ongoing release narrative lives. Knowing what's running and upgrading safely — that's the baseline contract the platform owes its customers, and version management is how we keep it.