paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-10-23 04:52:12 +00:00
Code Issues Packages Projects Releases Wiki Activity
Files
988622c5bb2820d9e0b63ae42da97ce16b81ac0a
zulip/docs/overview/release-lifecycle.md
Alya Abbott 988622c5bb docs: Clean up release lifecycle doc. 
- Split out roadmap page.
- Reorganize content.
- Clarify the major points and reduce redundancy.
2025-03-07 11:59:36 -08:00

8.7 KiB
Raw Blame History

Release lifecycle

This page provides an overview of Zulip server and client app release lifecycles. As discussed below, we highly recommend running the latest Zulip server release. We work extremely hard to make sure these releases are stable and have no regressions, and that the upgrade process Just Works.

New server releases are announced via the low-traffic zulip-announce email list. Please subscribe to get notified about new security releases.

Server and web app versions

The Zulip server and web app are developed together in the Zulip server repository.

Stable releases

:::{note}

The first digit of the Zulip server release version is its major release series (e.g., 9.4 is part of the 9.x series).

:::

Organizations self-hosting Zulip primarily use stable releases (e.g., Zulip {{ LATEST_RELEASE_VERSION }}).

  • New major releases, like Zulip 9.0, are published twice a year, and contain hundreds of features, bug fixes, and improvements to Zulip's internals.

  • New maintenance releases, like 9.4, are published roughly once a month. Maintenance releases are designed to have no risky changes and be easy to reverse, to minimize stress for administrators.

When upgrading to a new major release series, we recommend always upgrading to the latest maintenance release in that series, so that you use the latest version of the upgrade code.

Security releases

When we discover a security issue in Zulip, we publish a security and bug fix release, transparently documenting the issue using the industry-standard CVE advisory process.

When new security releases are published, we simultaneously publish the fixes to the main and stable release branches, so that anyone using those branches can immediately upgrade as well.

See also our security model documentation.

Git versions

Many Zulip servers run versions from Git that have not been published in a stable release.

  • You can upgrade to main for the latest changes.
  • We maintain Git branches with names like 9.x containing backported commits from main that we plan to include in the next maintenance release. Self-hosters can upgrade to these stable release branches to get bug fixes staged for the next stable release (which is very useful when you reported a bug whose fix we choose to backport). We support these branches as though they were a stable release.
  • The bleeding-edge server for the Zulip development community at https://chat.zulip.org runs the chat.zulip.org branch. It's upgraded to main several times a week. We also often "test deploy" changes not yet in main to this branch, to facilitate design feedback.
  • Zulip Cloud runs the zulip-cloud-current branch plus some cherry-picked changes. This branch is usually delayed by one to two weeks from main to allow for recent changes to be validated further prior to being deployed to customers.
  • You can also run a fork of Zulip.

What version am I running?

The Zulip web app displays the current server version in the gear menu; it's also available via the API.

Versioned documentation

To make sure you can access documentation for your server version, the help center, API documentation, and integrations documentation are distributed with the Zulip server itself (e.g., https://zulip.example.com/help/).

This ReadTheDocs documentation has a widget in the top left corner that lets you view the documentation for other versions.

Client apps

Zulip's official client apps support all Zulip server versions (and Git commits) released in the previous 18 months.

The API changelog details all changes to the API, to make it easy for client developers to maintain compatibility.

Mobile app

The Zulip mobile apps release new versions from the development branch frequently (usually every couple weeks). Except when fixing a critical bug, releases are first published to our beta channels.

Mobile and desktop client apps update automatically, unless a user disables automatic updates.

Desktop app

The Zulip desktop app is implemented in Electron, the browser-based desktop application framework used by essentially all modern chat applications. The Zulip UI in these apps is served from the Zulip server (and thus can vary between tabs when it is connected to organizations hosted by different servers).

The desktop app automatically updates soon after each new release. New desktop app releases rarely contain new features, because the desktop app tab inherits its features from the Zulip server/web app. However, it is important to upgrade because they often contain important security or OS compatibility fixes from the upstream Chromium project. Be sure to leave automatic updates enabled, or otherwise arrange to promptly upgrade after new security releases.

The Zulip server supports blocking access or displaying a warning to users attempting to access the server with extremely old or known insecure versions of the Zulip desktop and mobile apps, with an error message telling the user to upgrade.

Server and client app compatibility

Zulip is designed to make sure you can always run the latest server release (and we highly recommend that you do so!). We therefore generally do not backport changes to previous stable release series, except in rare cases involving a security issue or critical bug discovered just after publishing a major release.

The Zulip server preserves backwards compatibility in its API to support versions of the mobile and desktop apps released in the last 12 months. Because these clients auto-update, the vast majority of active clients will have upgraded by the time we desupport a version.

As noted above, Zulip's official client apps support all Zulip server versions (and Git commits) released in the previous 18 months.

Upgrade nag

The Zulip web app will display a banner warning users of a server running a Zulip release that is more than 18 months old, and is no longer officially supported by mobile and desktop apps. The nag will appear only to organization administrators starting a month before the deadline; after that, it will appear for all users on the server.

You can adjust the deadline for your installation by setting, for example, SERVER_UPGRADE_NAG_DEADLINE_DAYS = 30 * 21 in /etc/zulip/settings.py, and restarting the server.

:::{warning}

Servers older than 18 months are likely to be vulnerable to security bugs in Zulip or its upstream dependencies.

:::

Operating system support

For platforms we support, like Debian and Ubuntu, Zulip aims to support all versions of the upstream operating systems that are fully supported by the vendor. We document how to correctly upgrade the operating system for a Zulip server, including how to correctly chain upgrades when the latest Zulip release no longer supports your OS.

Note that we consider Ubuntu interim releases, which only have 8 months of security support, to be betas, not releases, and do not support them in production.

API bindings

The Zulip API bindings, and related projects like the Python and JavaScript bindings, are released independently as needed.