From d7d79b57b7ecc2f9c8ecee4097929d9605125cc9 Mon Sep 17 00:00:00 2001 From: Tim Abbott Date: Tue, 4 May 2021 16:39:27 -0700 Subject: [PATCH] docs: Replace legacy roadmap.md with release lifecycle page. This new pages accomplishes several interrelated things: * Documents that Zulip Cloud runs master and how that works. * Documents policies on how long client apps are expected to support old releases in our compatibility matrix. * Removes the 3-years-stale roadmap article. * Provides a central place to talk about different versions in Zulip. * Provides a better place to link to from our "you need to upgrade" nag. This content is not intended to be final, but should be finalized in the next week or so. Fixes #18322. --- SECURITY.md | 16 +- docs/_templates/layout.html | 2 +- docs/overview/index.rst | 2 +- docs/overview/release-lifecycle.md | 223 ++++++++++++++++++++++++ docs/overview/roadmap.md | 38 ---- docs/translating/translating.md | 17 +- templates/zerver/app/navbar_alerts.html | 2 +- 7 files changed, 252 insertions(+), 48 deletions(-) create mode 100644 docs/overview/release-lifecycle.md delete mode 100644 docs/overview/roadmap.md diff --git a/SECURITY.md b/SECURITY.md index 4bda8220ae..3411b57b44 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -14,15 +14,19 @@ response within 24 hours. Please include details on the issue and how you'd like to be credited in our release notes when we publish the fix. -Our [security -model](https://zulip.readthedocs.io/en/latest/production/security-model.html) -document may be a helpful resource. +Our [security model][security-model] document may be a helpful +resource. ## Supported versions Zulip provides security support for the latest major release, in the form of minor security/maintenance releases. -We work hard to make -[upgrades](https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-to-a-release) -reliable, so that there's no reason to run older major releases. +We work hard to make [upgrades][upgrades] reliable, so that there's no +reason to run older major releases. + +See also our documentation on the [Zulip release lifecycle][release-lifecycle] + +[security-model]: https://zulip.readthedocs.io/en/latest/production/security-model.html +[upgrades]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-to-a-release +[release-cycle]: https://zulip.readthedocs.io/en/latest/overview/release-lifecycle.html diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html index c82a7163d4..bb2805eff5 100644 --- a/docs/_templates/layout.html +++ b/docs/_templates/layout.html @@ -5,7 +5,7 @@ # version e.g. to say that something is likely to have changed. # For more info see: https://www.sphinx-doc.org/en/master/templating.html #} - {% if pagename in ["production/postgresql", "production/video-calls", "production/giphy-gif-integration"] and release.endswith('+git') %} + {% if pagename in ["overview/release-lifecycle", "production/postgresql", "production/video-calls", "production/giphy-gif-integration"] and release.endswith('+git') %} {# # This page doesn't exist in the stable documentation yet. # This temporary workaround prevents test failures and should be removed after the next release. diff --git a/docs/overview/index.rst b/docs/overview/index.rst index e8ad37a6e6..01c14aaedf 100644 --- a/docs/overview/index.rst +++ b/docs/overview/index.rst @@ -9,5 +9,5 @@ Overview contributing architecture-overview directory-structure - roadmap + release-lifecycle changelog diff --git a/docs/overview/release-lifecycle.md b/docs/overview/release-lifecycle.md new file mode 100644 index 0000000000..302fae81c0 --- /dev/null +++ b/docs/overview/release-lifecycle.md @@ -0,0 +1,223 @@ +# Release lifecycle + +This page documents how the various components of Zulip released are +managed as well as our backwards-compatibility and security support +policies. + +## Server and webapp + +The Zulip server and webapp are developed together in the [Zulip +server repository][zulip-server]. + +### Stable releases + +* Zulip Server **stable releases**, such as Zulip 4.5. + 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 "4.x"). (Before Zulip 3.0, + Zulip versions had another digit, e.g. 1.9.2 was a bug fix release + in the Zulip 1.9.x major release series). +* [New major releases][blog-major-releases], like Zulip 4.0, are + published every 3-6 months, and contain hundreds of features, bug + fixes, and improvements to Zulip's internals. +* New maintenance releases, like 4.3, 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. + +Starting with Zulip 4.0, the Zulip webapp displays the current server +version in the gear menu. With older releases, 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 +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/`). + +### Git versions + +Many Zulip servers run versions from Git that have not been published +in a stable release. + +* [Zulip Cloud](https://zulip.com) essentially runs the master + branch. It is usually a few days behind master (with some + cherry-picked bug fixes), but can fall up to 2 weeks behind when + major UI or internals changes mean we'd like to bake changes 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 master several times + every week. We also often "test deploy" changes not yet in master + to chat.zulip.org to facilitate design feedback. +* We maintain Git branches with names like `4.x` containing backported + commits from master 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). +* Self-hosters who want new features not yet present in a major + release can [upgrade to master][upgrading-to-master] 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-or-modify.md) Just Works. + +The Zulip server and clients 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 since 2.1.0. (They may also work + with older versions, with a degraded experience). +* 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. + +[blog-major-releases]: https://blog.zulip.com/tag/major-releases/ +[upgrade-from-git]: ../production/upgrade-or-modify.html#upgrading-from-a-git-repository + +### 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 +industry-standard [CVE advisory process](https://cve.mitre.org/). + +When new security releases are published, we simultaneously publish +the fixes to the `master` and stable release branches (E.g. `4.x`), 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 + +### Upgrade nag + +Starting with Zulip 4.0, the Zulip webapp 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. + +You can adjust the deadline for your installation by setting e.g. +`SERVER_UPGRADE_NAG_DEADLINE_DAYS = 30 * 21` in +`/etc/zulip/settings.py` and then [restarting the server](../production/settings.md). + +### 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][os-upgrade] 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][ubuntu-release-cycle], +which only have 8 months of security support, to be betas, not +releases, and do not support them in production. + +[ubuntu-release-cycle]: https://ubuntu.com/about/release-cycle + +### Server roadmap + +The Zulip server project uses several GitHub labels to structure +communication within the project about priorities: + +* The [high priority][label-high] label tags issues that we consider + important. This label is meant to be a determination of importance + that can be done quickly and then used as an input to planning + processes. +* The [release goal][label-release-goal] label is used for work that + we hope to include in the next major release. The related [post + release][label-post-release] label is used to track work we want to + focus on shortly after the next major release. + +The Zulip community feels strongly that all the little issues are, in +aggregate, just as important as the big things. Most resolved issues +do not have any of these priority labels. + +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](../contributing/chat-zulip-org.md) 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 [Reporting +issues](contributing.html#reporting-issues) 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 desktops apps are implemented in Electron + and thus contain a Chromium browser, security-conscious users should + not disable automatic updates. + + New desktop app releases rarely contain new features, because the + desktop app tab inherits its features from the Zulip server/webapp. + 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 +independently as needed. + +[electron]: https://www.electronjs.org/ +[upgrading-to-master]: ../production/upgrade-or-modify.html#upgrading-to-master +[os-upgrade]: ../production/upgrade-or-modify.html#upgrading-the-operating-system +[chat-zulip-org]: ../contributing/chat-zulip-org.md +[fork-zulip]: ../production/upgrade-or-modify.html#modifying-zulip +[zulip-server]: https://github.com/zulip/zulip + +[mobile-beta]: https://github.com/zulip/zulip-mobile#using-the-beta + +[label-blocker]: +https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22priority%3A+blocker%22 +[label-high]: +https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22priority%3A+high%22 +[label-release-goal]: +https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22release+goal%22 +[label-post-release]: +https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22post+release%22 diff --git a/docs/overview/roadmap.md b/docs/overview/roadmap.md deleted file mode 100644 index 731ebc69e3..0000000000 --- a/docs/overview/roadmap.md +++ /dev/null @@ -1,38 +0,0 @@ -# The Zulip roadmap - -Zulip has received a great deal of interest and attention since it was -released as free and open source software by Dropbox. That attention -has come with a lot of active development work from members of the -Zulip community. - -From when Zulip was released in September 2015 through today (November -2017), more than 350 people have contributed over 5000 pull requests to the -various Zulip repositories. So a lot of what gets done is driven by -contributor interest. That being said, our focus areas for the next few -months are: -* The mobile experience -* Visual polish of the main webapp -* Building out our API, bots and integrations framework -* Onboarding - -We also use the [blocker][label-blocker] and [high priority][label-high] -labels in the main server repository to more granularly track issues that -the project's leadership believes would significantly improve the project. -We should emphasize that the majority of issues resolved in regular -Zulip development are not tagged with one of these labels; while it's -essential to make progress on priority projects, the Zulip community feels -strongly that all the little issues are, in aggregate, just as important as -priority projects. - -We welcome participation from the community in influencing the Zulip -roadmap. If a bug or missing feature is causing significant pain for your -organization, we appreciate your commenting to that effect, either in -[chat.zulip.org](../contributing/chat-zulip-org.md) or on the -relevant GitHub issue, with an explanation of how the issue impacts -your use case. See [Reporting issues](contributing.html#reporting-issues) -for more information. - -[label-blocker]: -https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22priority%3A+blocker%22 -[label-high]: -https://github.com/zulip/zulip/issues?q=is%3Aissue+is%3Aopen+label%3A%22priority%3A+high%22 diff --git a/docs/translating/translating.md b/docs/translating/translating.md index 2699176db7..790f742918 100644 --- a/docs/translating/translating.md +++ b/docs/translating/translating.md @@ -40,7 +40,22 @@ progress, reporting problematic strings, etc. usually takes less than a day. You should then be able to access Zulip's dashboard in Transifex. -1. Translate the strings for your language in Transifex. +1. Translate the strings for your language in Transifex. Zulip has + several resource files: + * `mobile.json` is for the iOS/Android mobile apps. + * `desktop.json` is for the parts of the Zulip desktop apps that + are not shared with the Zulip webapp. + * `django.po` and `translations.json` have strings for the next + major release of the Zulip server and webapp (which is what we + run on chat.zulip.org and Zulip Cloud). + * The variants of `django.po` and `translations.json` with names + starting with a version, like, `4-x--`, are strings for Zulip's + current [stable release series](../overview/release-lifecycle.md). + + Transifex is smart about only asking you to translate a string once + even if it appears in multiple resources. The `4-x--` type variants + allow translators to get a language to 100% translated for the + current release. 1. If possible, test your translations (details below). diff --git a/templates/zerver/app/navbar_alerts.html b/templates/zerver/app/navbar_alerts.html index 25444d78f5..08e305d1d1 100644 --- a/templates/zerver/app/navbar_alerts.html +++ b/templates/zerver/app/navbar_alerts.html @@ -48,7 +48,7 @@
{{ _("This Zulip server is running an old version and should be upgraded.") }} - + {{ _("Learn more.") }}