mirror of
https://github.com/zulip/zulip.git
synced 2025-10-23 04:52:12 +00:00
docs: Clean up release lifecycle doc.
- Split out roadmap page. - Reorganize content. - Clarify the major points and reduce redundancy.
This commit is contained in:
@@ -9,5 +9,6 @@ readme
|
||||
architecture-overview
|
||||
directory-structure
|
||||
release-lifecycle
|
||||
roadmap
|
||||
changelog
|
||||
```
|
||||
|
@@ -1,151 +1,176 @@
|
||||
# Release lifecycle
|
||||
|
||||
This page details the release lifecycle for the Zulip server and
|
||||
client-apps, well as our policies around backwards-compatibility and
|
||||
security support policies. In short:
|
||||
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](#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
|
||||
and servers. Server upgrades are designed to Just Work; mobile and
|
||||
desktop client apps update automatically.
|
||||
- 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.
|
||||
New server releases are announced via the low-traffic [zulip-announce email
|
||||
list](https://groups.google.com/g/zulip-announce). Please subscribe to get
|
||||
notified about new security releases.
|
||||
|
||||
## Server and web app
|
||||
## Server and web app versions
|
||||
|
||||
The Zulip server and web app are developed together in the [Zulip
|
||||
server repository][zulip-server].
|
||||
|
||||
### Stable releases
|
||||
|
||||
- Zulip Server **stable releases**, such as Zulip 9.4.
|
||||
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].
|
||||
:::{note}
|
||||
|
||||
The Zulip web app displays the current server version [in the gear
|
||||
menu](https://zulip.com/help/view-zulip-version). With older releases,
|
||||
the server version is available [via the
|
||||
API](https://zulip.com/api/get-server-settings).
|
||||
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).
|
||||
|
||||
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
|
||||
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/`).
|
||||
:::
|
||||
|
||||
Organizations self-hosting Zulip primarily use stable releases (e.g., Zulip {{
|
||||
LATEST_RELEASE_VERSION }}).
|
||||
|
||||
- [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-releases]: https://blog.zulip.com/tag/release-announcements/
|
||||
|
||||
### Git versions
|
||||
|
||||
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
|
||||
#### Security releases
|
||||
|
||||
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/).
|
||||
|
||||
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.
|
||||
|
||||
See also our [security model][security-model] documentation.
|
||||
|
||||
[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
|
||||
|
||||
The Zulip web app will display a banner warning users of a server
|
||||
running a Zulip release that is more than 18 months old. We do this
|
||||
for a few reasons:
|
||||
|
||||
- It is unlikely that a server of that age is not vulnerable to
|
||||
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.
|
||||
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 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
|
||||
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
|
||||
|
||||
### 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
|
||||
|
||||
The Zulip API bindings and related projects maintained by the Zulip
|
||||
core community, like the Python and JavaScript bindings, are released
|
||||
The [Zulip API](https://zulip.com/api/) bindings, and related projects like the
|
||||
[Python](https://zulip.com/api/configuring-python-bindings) and
|
||||
[JavaScript](https://github.com/zulip/zulip-js#readme) bindings, are released
|
||||
independently as needed.
|
||||
|
||||
[electron]: https://www.electronjs.org/
|
||||
|
47
docs/overview/roadmap.md
Normal file
47
docs/overview/roadmap.md
Normal 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/).
|
Reference in New Issue
Block a user