paulmataruso/zulip
1
0
Fork 0
mirror of https://github.com/zulip/zulip.git synced 2025-11-01 20:44:04 +00:00
Code Issues Packages Projects Releases Wiki Activity

docs: Clean up release lifecycle doc.

Browse Source 
- Split out roadmap page.
- Reorganize content.
- Clarify the major points and reduce redundancy.
This commit is contained in:
Alya Abbott
2025-03-06 15:30:39 -08:00
committed by Tim Abbott
parent 4246d42d91
commit 988622c5bb
3 changed files with 192 additions and 186 deletions
Download Patch File Download Diff File Expand all files Collapse all files

1
docs/overview/index.md
View File

@@ -9,5 +9,6 @@ readme
architecture-overview architecture-overview
directory-structure directory-structure
release-lifecycle release-lifecycle
roadmap
changelog changelog
``` ```

330
docs/overview/release-lifecycle.md
View File

@@ -1,151 +1,176 @@
# Release lifecycle # Release lifecycle
This page details the release lifecycle for the Zulip server and This page provides an overview of Zulip server and client app release
client-apps, well as our policies around backwards-compatibility and lifecycles. As discussed below, we highly recommend running [the latest Zulip
security support policies. In short: server release](#stable-releases). We work extremely hard to make sure these
releases are stable and have no regressions, and that the [upgrade
process](../production/upgrade.md) Just Works.
- We recommend always running the latest releases of the Zulip clients New server releases are announced via the low-traffic [zulip-announce email
and servers. Server upgrades are designed to Just Work; mobile and list](https://groups.google.com/g/zulip-announce). Please subscribe to get
desktop client apps update automatically. notified about new security releases.
- The server and client apps are backwards and forwards compatible
across a wide range of versions. So while it's important to upgrade
the server to get security updates, bug fixes, and new features, the
mobile and desktop apps will continue working for at least 18 months
if you don't do so.
- New server releases are announced via the low-traffic
[zulip-announce email
list](https://groups.google.com/g/zulip-announce). We
highly recommend subscribing so that you are notified about new
security releases.
- Zulip Cloud runs the branch that will become the next major
server/web app release, so it is always "newer" than the latest
stable release.
## Server and web app ## Server and web app versions
The Zulip server and web app are developed together in the [Zulip The Zulip server and web app are developed together in the [Zulip
server repository][zulip-server]. server repository][zulip-server].
### Stable releases ### Stable releases
- Zulip Server **stable releases**, such as Zulip 9.4. :::{note}
Organizations self-hosting Zulip primarily use stable releases.
- The numbering scheme is simple: the first digit indicates the major
release series (which we'll refer to as "9.x").
- [New major releases][blog-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.
- For the dates of past stable releases,
[see the Zulip blog][blog-releases].
The Zulip web app displays the current server version [in the gear The first digit of the Zulip server release version is its major release series
menu](https://zulip.com/help/view-zulip-version). With older releases, (e.g., 9.4 is part of the 9.x series).
the server version is available [via the
API](https://zulip.com/api/get-server-settings).
This ReadTheDocs documentation has a widget in the lower-left corner :::
that lets you view the documentation for other versions. Other
documentation, like our [Help Center](https://zulip.com/help/), [API Organizations self-hosting Zulip primarily use stable releases (e.g., Zulip {{
documentation](https://zulip.com/api/), and [Integrations LATEST_RELEASE_VERSION }}).
documentation](https://zulip.com/integrations/), are distributed with
the Zulip server itself (e.g., `https://zulip.example.com/help/`). - [New major releases][blog-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.
[blog-major-releases]: https://blog.zulip.com/tag/major-releases/ [blog-major-releases]: https://blog.zulip.com/tag/major-releases/
[blog-releases]: https://blog.zulip.com/tag/release-announcements/
### Git versions #### Security releases
Many Zulip servers run versions from Git that have not been published
in a stable release.
- [Zulip Cloud](https://zulip.com) runs the `zulip-cloud-current`
branch; this the `main` branch, with some cherry-picked bug fixes,
but delayed somewhat. It is usually one to two weeks behind `main`,
depending on the complexity of recent major UI or internals changes
that we'd like to bake longer on chat.zulip.org before exposing them
to the full Zulip Cloud userbase.
- [chat.zulip.org][chat-zulip-org], the bleeding-edge server for the
Zulip development community, is upgraded to `main` several times
every week. We also often "test deploy" changes not yet in `main`
to chat.zulip.org to facilitate design feedback.
- We maintain Git branches with names like `7.x` containing backported
commits from `main` that we plan to include in the next maintenance
release. Self-hosters can [upgrade][upgrade-from-git] 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.
- Self-hosters who want new features not yet present in a major
release can [upgrade to `main`][upgrading-to-main] or run [a fork
of Zulip][fork-zulip].
### Compatibility and upgrading
A Zulip design goal is for there never to be a reason to run an old
version of Zulip. We work extremely hard to make sure Zulip is stable
for self-hosters, has no regressions, and that the [Zulip upgrade
process](../production/upgrade.md) Just Works.
The Zulip server and client apps are all carefully engineered to
ensure compatibility with old versions. In particular:
- The Zulip mobile and desktop apps maintain backwards-compatibility
code to support any Zulip server version from the last 18 months.
- Zulip maintains an [API changelog](https://zulip.com/api/changelog)
detailing all changes to the API to make it easy for client
developers to do this correctly.
- The Zulip server preserves backwards-compatibility in its API to
support versions of the mobile and desktop apps released in roughly
the last year. Because these clients auto-update, generally there
are only a handful of active clients left by the time we desupport a
version.
As a result, we generally do not backport changes to previous stable
release series except in rare cases involving a security issue or
critical bug just after publishing a major release.
[upgrade-from-git]: ../production/upgrade.md#upgrading-from-a-git-repository
### Security releases
When we discover a security issue in Zulip, we publish a security and When we discover a security issue in Zulip, we publish a security and
bug fix release, transparently documenting the issue(s) using the bug fix release, transparently documenting the issue using the
industry-standard [CVE advisory process](https://cve.mitre.org/). industry-standard [CVE advisory process](https://cve.mitre.org/).
When new security releases are published, we simultaneously publish When new security releases are published, we simultaneously publish
the fixes to the `main` and stable release branches (e.g., `9.x`), so the fixes to the `main` and stable release branches, so
that anyone using those branches can immediately upgrade as well. that anyone using those branches can immediately upgrade as well.
See also our [security model][security-model] documentation. See also our [security model][security-model] documentation.
[security-model]: ../production/security-model.md [security-model]: ../production/security-model.md
### Git versions
Many Zulip servers run versions from Git that have not been published
in a stable release.
- You can [upgrade to `main`][upgrading-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][upgrade-from-git] 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][chat-zulip-org]
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](https://zulip.com) 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][fork-zulip].
[upgrade-from-git]: ../production/upgrade.md#upgrading-from-a-git-repository
### What version am I running?
The Zulip web app displays the current server version [in the gear
menu](https://zulip.com/help/view-zulip-version); it's also available [via the
API](https://zulip.com/api/get-server-settings).
### Versioned documentation
To make sure you can access documentation for your server version, [the help
center](https://zulip.com/help/), [API documentation](https://zulip.com/api/),
and [integrations documentation](https://zulip.com/integrations/) 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](https://zulip.com/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-beta].
Mobile and desktop client apps update automatically, unless a user disables
automatic updates.
### Desktop app
The Zulip [desktop app](https://zulip.com/apps/) is implemented in
[Electron][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](#server-and-web-app-versions) (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](#client-apps), Zulip's official client apps support all Zulip
server versions (and Git commits) released in the **previous 18 months**.
### Upgrade nag ### Upgrade nag
The Zulip web app will display a banner warning users of a server The Zulip web app will display a banner warning users of a server running a
running a Zulip release that is more than 18 months old. We do this Zulip release that is more than 18 months old, and is no longer officially
for a few reasons: 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
- It is unlikely that a server of that age is not vulnerable to for all users on the server.
a security bug in Zulip or one of its dependencies.
- The Zulip mobile and desktop apps are only guaranteed to support
server versions less than 18 months old.
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 You can adjust the deadline for your installation by setting, for
example, `SERVER_UPGRADE_NAG_DEADLINE_DAYS = 30 * 21` in example, `SERVER_UPGRADE_NAG_DEADLINE_DAYS = 30 * 21` in
`/etc/zulip/settings.py` and then [restarting the server](../production/settings.md). `/etc/zulip/settings.py`, and [restarting the server](../production/settings.md).
### Operating system support :::{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 For platforms we support, like Debian and Ubuntu, Zulip aims to
support all versions of the upstream operating systems that are fully support all versions of the upstream operating systems that are fully
@@ -160,78 +185,11 @@ releases, and do not support them in production.
[ubuntu-release-cycle]: https://ubuntu.com/about/release-cycle [ubuntu-release-cycle]: https://ubuntu.com/about/release-cycle
### Server roadmap
The Zulip server project uses GitHub projects and labels to structure
communication about priorities:
- We use a [GitHub project
board](https://github.com/orgs/zulip/projects/9/views/13) to publicly track
goals for major releases. The items with the "Done" status will be included in
the next major release. Otherwise, the project board should be seen a list of
priorities being _considered_ for the release, not a guarantee that features
will be included. As the release date approaches, features that will not make
it into the release are dropped from the project board on an ongoing basis.
- The [high priority][label-high] label tags issues that we consider important.
It is reviewed in the planning stage of the release cycle to identify
priorities for the next release.
- The [help wanted][label-help-wanted] label tags issues that are open for
contributions.
The Zulip community feels strongly that all the little issues are, in
aggregate, just as important as the big things. Many resolved issues
are never explicitly tagged as release goals.
We welcome participation from our user community in influencing the Zulip
roadmap. If a bug or missing feature is causing significant pain for you, we'd
love to hear from you, either in
[chat.zulip.org](https://zulip.com/development-community/) or on the relevant
GitHub issue. Please an include an explanation of your use case: such details
can be extremely helpful in designing appropriately general solutions, and also
helps us identify cases where an existing solution can solve your problem. See
our guide on [suggesting features and
improvements](../contributing/suggesting-features.md) for more details.
## Client apps
Zulip's client apps officially support all Zulip server versions (and
Git commits) released in the previous 18 months, matching the behavior
of our [upgrade nag](#upgrade-nag).
- 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-beta].
- The Zulip desktop apps are implemented in [Electron][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 apps automatically update soon after each new
release. Because Zulip's desktop apps are implemented in Electron
and thus contain a Chromium browser, security-conscious users should
leave automatic updates enabled or otherwise arrange to promptly
upgrade all users after a new security 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.
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.
## API bindings ## API bindings
The Zulip API bindings and related projects maintained by the Zulip The [Zulip API](https://zulip.com/api/) bindings, and related projects like the
core community, like the Python and JavaScript bindings, are released [Python](https://zulip.com/api/configuring-python-bindings) and
[JavaScript](https://github.com/zulip/zulip-js#readme) bindings, are released
independently as needed. independently as needed.
[electron]: https://www.electronjs.org/ [electron]: https://www.electronjs.org/

47
docs/overview/roadmap.md Normal file
View File

@@ -0,0 +1,47 @@
# Roadmap
We welcome participation from our user community in influencing the Zulip
roadmap. If a bug or missing feature is causing significant pain for you, we'd
love to hear from you, either in
[chat.zulip.org](https://zulip.com/development-community/) or on the relevant
GitHub issue.
Please an include an explanation of your use case: such details can be extremely
helpful in designing appropriately general solutions, and also helps us identify
cases where an existing solution can solve your problem. See our guide on
[suggesting features and improvements](../contributing/suggesting-features.md)
for more details.
## Server and web app roadmap
The Zulip server project uses GitHub projects and labels to structure
communication about priorities:
- We use a [GitHub project
board](https://github.com/orgs/zulip/projects/9/views/13) to publicly track
goals for major releases. The items with the "Done" status will be included in
the next major release. Otherwise, the project board should be seen a list of
priorities being _considered_ for the release, not a guarantee that features
will be included. As the release date approaches, features that will not make
it into the release are dropped from the project board on an ongoing basis.
- The [high priority][label-high] label tags issues that we consider important.
It is reviewed in the planning stage of the release cycle to identify
priorities for the next release.
- The [help wanted][label-help-wanted] label tags issues that are open for
contributions.
The Zulip community feels strongly that all the little issues are, in
aggregate, just as important as the big things. Many resolved issues
are never explicitly tagged as release goals.
[label-high]: https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22priority%3A+high%22
[label-help-wanted]: https://github.com/zulip/zulip/issues?q=is%3Aopen+is%3Aissue+label%3A%22help+wanted%22
## Mobile app roadmap
We use a [GitHub project
board](https://github.com/orgs/zulip/projects/5/views/4) to publicly track
milestones for Zulip's [next-generation mobile
app](https://blog.zulip.com/2024/12/12/new-flutter-mobile-app-beta/).