From af4d7b4b52c5af46bc9cb9f61d88c0d9ecf2fc4f Mon Sep 17 00:00:00 2001
From: David Rosa <rosatamsen@gmail.com>
Date: Mon, 14 Oct 2019 12:40:48 -0700
Subject: [PATCH] docs: Merge "Upgrading" with modifying-zulip.

Merges the "Upgrades" section from production/maintain-secure-upgrade.md
with production/modifying-zulip.md.

Contains significant textual changes by tabbott to read more clearly.
---
 docs/_templates/layout.html                   |   2 +-
 docs/overview/changelog.md                    |   6 +-
 docs/production/deployment.md                 |   2 +-
 docs/production/export-and-import.md          |   2 +-
 docs/production/index.rst                     |   2 +-
 docs/production/install.md                    |   4 +-
 docs/production/maintain-secure-upgrade.md    | 411 ++-----------
 docs/production/mobile-push-notifications.md  |   2 +-
 docs/production/modifying-zulip.md            | 210 -------
 docs/production/settings.md                   |   4 +-
 docs/production/upgrade-or-modify.md          | 574 ++++++++++++++++++
 templates/zerver/help/import-from-gitter.md   |   2 +-
 templates/zerver/help/import-from-hipchat.md  |   4 +-
 .../zerver/help/import-from-mattermost.md     |   4 +-
 templates/zerver/help/import-from-slack.md    |   2 +-
 15 files changed, 643 insertions(+), 588 deletions(-)
 delete mode 100644 docs/production/modifying-zulip.md
 create mode 100644 docs/production/upgrade-or-modify.md

diff --git a/docs/_templates/layout.html b/docs/_templates/layout.html
index 1c4e40f063..b13512162c 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 == "production/email-gateway" or pagename == "production/modifying-zulip") and release.endswith('+git') %}
+    {% if (pagename == "production/email-gateway" or pagename == "production/upgrade-or-modify") and release.endswith('+git') %}
     <!--
     # email-gateway.html page doesn't exist in the stable documentation yet.
     # This temporary workaround prevents CircleCI failure and should be removed after the next release.
diff --git a/docs/overview/changelog.md b/docs/overview/changelog.md
index 01ed725051..6ce39a6177 100644
--- a/docs/overview/changelog.md
+++ b/docs/overview/changelog.md
@@ -43,7 +43,7 @@ in bursts.
   readable style.
 - We merged significant preparatory work for supporting RHEL/CentOS in
   production.  We're now interested in beta testers for this feature.
-- Added [new documentation](../production/modifying-zulip.md) on
+- Added [new documentation](../production/upgrade-or-modify.html#modifying-zulip) on
   maintaining a fork of Zulip.
 - Added new `streams:public` search operator that searches the public
   history of all streams in the organization (even before you joined).
@@ -440,7 +440,7 @@ Zulip installations; it has minimal changes for existing servers.
   phase of the upgrade closely, we recommend
   [running them first manually](../production/expensive-migrations.md)
   and as well as the usual trick of
-  [doing an apt upgrade first](../production/maintain-secure-upgrade.html#applying-system-updates).
+  [doing an apt upgrade first](../production/upgrade-or-modify.html#applying-system-updates).
 
 **Full feature changelog:**
 - Added an organization setting for message deletion time limits.
@@ -818,7 +818,7 @@ Backend and scaling
   phase of the upgrade closely, we recommend
   [running them first manually](../production/expensive-migrations.md) and as well
   as the usual trick of
-  [doing an apt upgrade first](../production/maintain-secure-upgrade.html#applying-system-updates).
+  [doing an apt upgrade first](../production/upgrade-or-modify.html#applying-system-updates).
 
 * We've removed support for an uncommon legacy deployment model where
   a Zulip server served multiple organizations on the same domain.
diff --git a/docs/production/deployment.md b/docs/production/deployment.md
index acdaa8a54c..1237382d8a 100644
--- a/docs/production/deployment.md
+++ b/docs/production/deployment.md
@@ -19,7 +19,7 @@ git clone https://github.com/zulip/zulip.git zulip-server-git
 
 and then
 [continue the normal installation instructions](../production/install.html#step-2-install-zulip).
-You can also [upgrade Zulip from Git](../production/maintain-secure-upgrade.html#upgrading-from-a-git-repository).
+You can also [upgrade Zulip from Git](../production/upgrade-or-modify.html#upgrading-from-a-git-repository).
 
 ## Zulip in Docker
 
diff --git a/docs/production/export-and-import.md b/docs/production/export-and-import.md
index 8de2d7e637..9f6aafbd08 100644
--- a/docs/production/export-and-import.md
+++ b/docs/production/export-and-import.md
@@ -338,7 +338,7 @@ cd /home/zulip/deployments/current
 This could take several minutes to run depending on how much data you're
 importing.
 
-[upgrade-zulip-from-git]: ../production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
+[upgrade-zulip-from-git]: ../production/upgrade-or-modify.html#upgrading-from-a-git-repository
 
 #### Import options
 
diff --git a/docs/production/index.rst b/docs/production/index.rst
index 090f09b320..3af76a3470 100644
--- a/docs/production/index.rst
+++ b/docs/production/index.rst
@@ -11,6 +11,7 @@ Zulip in Production
    settings
    mobile-push-notifications
    maintain-secure-upgrade
+   upgrade-or-modify
    security-model
    authentication-methods
    export-and-import
@@ -20,4 +21,3 @@ Zulip in Production
    email
    deployment
    email-gateway
-   modifying-zulip
diff --git a/docs/production/install.md b/docs/production/install.md
index f0e643aa82..ca22b794c9 100644
--- a/docs/production/install.md
+++ b/docs/production/install.md
@@ -109,7 +109,9 @@ for server administrators.  This extremely low-traffic list is for
 important announcements, including new releases and security issues.
 * Follow [Zulip on Twitter](https://twitter.com/zulip).
 * Learn how to [configure your Zulip server settings](settings.md).
-* Learn about [maintaining a production Zulip server](maintain-secure-upgrade.md).
+* Learn about [maintaining](../production/maintain-secure-upgrade.md)
+and [upgrading](../production/upgrade-or-modify.md) a production Zulip
+server.
 
 [realm-admin-docs]: https://zulipchat.com/help/getting-your-organization-started-with-zulip
 
diff --git a/docs/production/maintain-secure-upgrade.md b/docs/production/maintain-secure-upgrade.md
index 3efdd6c26c..1f876f7d40 100644
--- a/docs/production/maintain-secure-upgrade.md
+++ b/docs/production/maintain-secure-upgrade.md
@@ -1,11 +1,8 @@
-# Secure, maintain, and upgrade
+# Maintain, secure, and upgrade
 
 This page covers topics that will help you maintain a healthy, up-to-date, and
 secure Zulip installation, including:
 
-- [Upgrading](#upgrading)
-- [Upgrading from a git repository](#upgrading-from-a-git-repository)
-- [Upgrading the operating system](#upgrading-the-operating-system)
 - [Monitoring](#monitoring)
 - [Scalability](#scalability)
 - [Management commands](#management-commands)
@@ -13,360 +10,8 @@ secure Zulip installation, including:
 You may also want to read this related content:
 
 - [Security Model](../production/security-model.md)
-
-## Upgrading
-
-**We recommend reading this entire section before doing your first
-upgrade.**
-
-To upgrade to a new version of the zulip server, download the appropriate
-release tarball from <https://www.zulip.org/dist/releases/>.
-
-You also have the option of creating your own release tarballs from a
-copy of the [zulip.git repository](https://github.com/zulip/zulip)
-using `tools/build-release-tarball` or upgrade Zulip
-[to a version in a Git repository directly](#upgrading-from-a-git-repository).
-
-Next, run as root:
-
-```
-/home/zulip/deployments/current/scripts/upgrade-zulip zulip-server-VERSION.tar.gz
-```
-
-The upgrade process will shut down the Zulip service and then run `apt-get upgrade`, a
-puppet apply, any database migrations, and then bring the Zulip service back
-up. Upgrading will result in some brief downtime for the service, which should be
-under 30 seconds unless there is an expensive transition involved. Unless you
-have tested the upgrade in advance, we recommend doing upgrades at off hours.
-
-(Note that there are
-[separate instructions for upgrading Zulip if you're using Docker][docker-upgrade].)
-
-[docker-upgrade]: https://github.com/zulip/docker-zulip#upgrading-the-zulip-container
-
-### Preserving local changes to configuration files
-
-**Warning**: If you have modified configuration files installed by
-Zulip (e.g. the nginx configuration), the Zulip upgrade process will
-overwrite your configuration when it does the `puppet apply`.
-
-You can test whether this will happen assuming no upstream changes to
-the configuration using `scripts/zulip-puppet-apply` (without the
-`-f` option), which will do a test puppet run and output and changes
-it would make. Using this list, you can save a copy of any files
-that you've modified, do the upgrade, and then restore your
-configuration.
-
-That said, Zulip's configuration files are designed to be flexible
-enough for a wide range of installations, from a small self-hosted
-system to Zulip Cloud.  Before making local changes to a configuration
-file, first check whether there's an option supported by
-`/etc/zulip/zulip.conf` for the customization you need.  And if you
-need to make local modifications, please report the issue so that we
-can make the Zulip puppet configuration flexible enough to handle your
-setup.
-
-#### nginx configuration changes
-
-If you need to modify Zulip's `nginx` configuration, we recommend
-first attempting to add configuration to `/etc/nginx/conf.d` or
-`/etc/nginx/zulip-include/app.d`; those directories are designed for
-custom configuration.
-
-### Troubleshooting with the upgrade log
-
-The Zulip upgrade script automatically logs output to
-`/var/log/zulip/upgrade.log`. Please use those logs to include output
-that shows all errors in any bug reports.
-
-After the upgrade, we recommend checking `/var/log/zulip/errors.log`
-to confirm that your users are not experiencing errors after the
-upgrade.
-
-### Rolling back to a prior version
-
-The Zulip upgrade process works by creating a new deployment under
-`/home/zulip/deployments/` containing a complete copy of the Zulip server code,
-and then moving the symlinks at `/home/zulip/deployments/{current,last,next}`
-as part of the upgrade process.
-
-This means that if the new version isn't working,
-you can quickly downgrade to the old version by running
-`/home/zulip/deployments/last/scripts/restart-server`, or to an
-earlier previous version by running
-`/home/zulip/deployments/DATE/scripts/restart-server`.  The
-`restart-server` script stops any running Zulip server, and starts
-the version corresponding to the `restart-server` path you call.
-
-### Updating settings
-
-If required, you can update your settings by editing `/etc/zulip/settings.py`
-and then run `/home/zulip/deployments/current/scripts/restart-server` to
-restart the server.
-
-### Applying system updates
-
-The Zulip upgrade script will automatically run `apt-get update` and
-then `apt-get upgrade`, to make sure you have any new versions of
-dependencies (this will also update system packages).  We assume that
-you will install security updates from `apt` regularly, according to
-your usual security practices for a production server.
-
-If you'd like to minimize downtime when installing a Zulip server
-upgrade, you may want to do an `apt-get upgrade` (and then restart the
-server and check everything is working) before running the Zulip
-upgrade script.
-
-There's one `apt` package to be careful about: upgrading `postgresql`
-while the server is running may result in an outage (basically,
-`postgresql` might stop accepting new queries but refuse to shut down
-while waiting for connections from the Zulip server to shut down).
-While this only happens sometimes, it can be hard to fix for someone
-who isn't comfortable managing a `postgresql` database [1].  You can
-avoid that possibility with the following procedure (run as root):
-
-```
-apt-get update
-supervisorctl stop all
-apt-get upgrade -y
-supervisorctl start all
-```
-
-[1] If this happens to you, just stop the Zulip server, restart
-postgres, and then start the Zulip server again, and you'll be back in
-business.
-
-#### Disabling unattended upgrades
-
-**Important**: We recommend that you
-[disable Ubuntu's unattended-upgrades][disable-unattended-upgrades],
-and instead install apt upgrades manually.  With unattended upgrades
-enabled, the moment a new Postgres release is published, your Zulip
-server will have its postgres server upgraded (and thus restarted).
-
-When one of the services Zulip depends on (postgres, memcached, redis,
-rabbitmq) is restarted, that services will disconnect everything using
-them (like the Zulip server), and every operation that Zulip does
-which uses that service will throw an exception (and send you an error
-report email).  These apparently "random errors" can be confusing and
-might cause you to worry incorrectly about the stability of the Zulip
-software, which in fact the problem is that Ubuntu automatically
-upgraded and then restarted key Zulip dependencies.
-
-Instead, we recommend installing updates for these services manually,
-and then restarting the Zulip server with
-`/home/zulip/deployments/current/scripts/restart-server` afterwards.
-
-[disable-unattended-upgrades]: https://linoxide.com/ubuntu-how-to/enable-disable-unattended-upgrades-ubuntu-16-04/
-
-### API and your Zulip URL
-
-To use the Zulip API with your Zulip server, you will need to use the
-API endpoint of e.g. `https://zulip.example.com/api`.  Our Python
-API example scripts support this via the
-`--site=https://zulip.example.com` argument.  The API bindings
-support it via putting `site=https://zulip.example.com` in your
-.zuliprc.
-
-Every Zulip integration supports this sort of argument (or e.g. a
-`ZULIP_SITE` variable in a zuliprc file or the environment), but this
-is not yet documented for some of the integrations (the included
-integration documentation on `/integrations` will properly document
-how to do this for most integrations).  We welcome pull requests for
-integrations that don't discuss this!
-
-Similarly, you will need to instruct your users to specify the URL
-for your Zulip server when using the Zulip desktop and mobile apps.
-
-### Memory leak mitigation
-
-As a measure to mitigate the impact of potential memory leaks in one
-of the Zulip daemons, the service automatically restarts itself
-every Sunday early morning.  See `/etc/cron.d/restart-zulip` for the
-precise configuration.
-
-## Upgrading from a git repository
-
-Zulip supports upgrading a production installation to any commit in
-Git, which is great for running pre-release versions or maintaining a
-small fork.  If you're using Zulip 1.7 or newer, you can just run the
-command:
-
-```
-# Upgrade to a tagged release
-/home/zulip/deployments/current/scripts/upgrade-zulip-from-git 1.8.1
-# Upgrade to a branch or other Git ref
-/home/zulip/deployments/current/scripts/upgrade-zulip-from-git master
-```
-
-and Zulip will automatically fetch the relevant Git commit and upgrade
-to that version of Zulip.
-
-By default, this uses the main upstream Zulip server repository
-(example below), but you can configure any other Git repository by
-adding a section like this to `/etc/zulip/zulip.conf`:
-
-```
-[deployment]
-git_repo_url = https://github.com/zulip/zulip.git
-```
-
-See also our documentation on [modifying
-Zulip](../production/modifying-zulip.md) and [upgrading
-docker-zulip](https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository).
-
-**Systems with limited RAM**: If you are running a minimal Zulip
-  server with 2GB of RAM or less, the upgrade can fail due to the
-  system running out of RAM running both the Zulip server and Zulip's
-  static asset build process (`tools/webpack`
-  is usually the step that fails).  If you encounter this,
-  you can run `supervisorctl stop all` to shut down the Zulip server
-  while you run the upgrade (this will, of course, add some downtime,
-  which is part of we already recommend more RAM for organizations of
-  more than a few people).
-
-### Upgrading using Git from Zulip 1.6 and older
-
-If you're are upgrading from a Git repository, and you currently have
-Zulip 1.6 or older installed, you will need to install the
-dependencies for building Zulip's static assets.  To do this, add
-`zulip::static_asset_compiler` to your `/etc/zulip/zulip.conf` file's
-`puppet_classes` entry, like this:
-
-```
-puppet_classes = zulip::voyager, zulip::static_asset_compiler
-```
-
-and run `scripts/zulip-puppet-apply`.  After approving the changes,
-you'll be able to use `upgrade-zulip-from-git`.
-
-After you've upgraded to Zulip 1.7 or above, you can safely remove
-`zulip::static_asset_compiler` from `puppet_classes`; in Zulip 1.7 and
-above, it is a dependency of `zulip::voyager` and thus these
-dependencies are installed by default.
-
-## Upgrading the operating system
-
-When you upgrade the operating system on which Zulip is installed
-(E.g. Ubuntu 14.04 Trusty to Ubuntu 16.04 Xenial), you need to take
-some additional steps to update your Zulip installation, documented
-below.
-
-The steps are largely the same for the various OS upgrades aside from
-the versions of postgres, so you should be able to adapt these
-instructions for other supported platforms.
-
-### Upgrading from Ubuntu 14.04 Trusty to 16.04 Xenial
-
-1. First, as the Zulip user, stop the Zulip server and run the following
-to back up the system:
-
-    ```
-    supervisorctl stop all
-    /home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
-    ```
-
-2. Switch to the root user and upgrade the operating system using the
-OS's standard tooling.  E.g. for Ubuntu, this means running
-`do-release-upgrade` and following the prompts until it completes
-successfully:
-
-    ```
-    sudo -i # Or otherwise get a root shell
-    do-release-upgrade
-    ```
-
-    When `do-release-upgrade` asks you how to upgrade configuration
-    files for services that Zulip manages like `redis`, `postgres`,
-    `nginx`, and `memcached`, the best choice is `N` to keep the
-    currently installed version.  But it's not important; the next
-    step will re-install Zulip's configuration in any case.
-
-3. As root, upgrade the database installation and OS configuration to
-match the new OS version:
-
-    ```
-    apt remove upstart -y
-    /home/zulip/deployments/current/scripts/zulip-puppet-apply -f
-    pg_dropcluster 9.5 main --stop
-    systemctl stop postgresql
-    pg_upgradecluster -m upgrade 9.3 main
-    pg_dropcluster 9.3 main
-    apt remove postgresql-9.3
-    systemctl start postgresql
-    service memcached restart
-    ```
-
-4. At this point, you are now running the version of postgres that
-comes with the new Ubuntu version.  Finally, we need to reinstall the
-current version of Zulip, which among other things will recompile
-Zulip's Python module dependencies for your new version of Python:
-
-    ```
-    rm -rf /srv/zulip-venv-cache/*
-    /home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
-        /home/zulip/deployments/current/ --ignore-static-assets
-    ```
-
-That last command will finish by restarting your Zulip server; you
-should now be able to navigate to its URL and confirm everything is
-working correctly.
-
-### Upgrading from Ubuntu 16.04 Xenial to 18.04 Bionic
-
-1. First, as the Zulip user, stop the Zulip server and run the following
-to back up the system:
-
-    ```
-    supervisorctl stop all
-    /home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
-    ```
-
-2. Switch to the root user and upgrade the operating system using the
-OS's standard tooling.  E.g. for Ubuntu, this means running
-`do-release-upgrade` and following the prompts until it completes
-successfully:
-
-    ```
-    sudo -i # Or otherwise get a root shell
-    do-release-upgrade
-    ```
-
-    When `do-release-upgrade` asks you how to upgrade configuration
-    files for services that Zulip manages like `redis`, `postgres`,
-    `nginx`, and `memcached`, the best choice is `N` to keep the
-    currently installed version.  But it's not important; the next
-    step will re-install Zulip's configuration in any case.
-
-3. As root, upgrade the database installation and OS configuration to
-match the new OS version:
-
-    ```
-    touch /usr/share/postgresql/10/pgroonga_setup.sql.applied
-    /home/zulip/deployments/current/scripts/zulip-puppet-apply -f
-    pg_dropcluster 10 main --stop
-    systemctl stop postgresql
-    pg_upgradecluster 9.5 main
-    pg_dropcluster 9.5 main
-    apt remove postgresql-9.5
-    systemctl start postgresql
-    systemctl restart memcached
-    ```
-
-4. At this point, you are now running the version of postgres that
-comes with the new Ubuntu version.  Finally, we need to reinstall the
-current version of Zulip, which among other things will recompile
-Zulip's Python module dependencies for your new version of Python:
-
-    ```
-    rm -rf /srv/zulip-venv-cache/*
-    /home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
-        /home/zulip/deployments/current/ --ignore-static-assets
-    ```
-
-That last command will finish by restarting your Zulip server; you
-should now be able to navigate to its URL and confirm everything is
-working correctly.
+- [Backups, export and import](../production/export-and-import.md)
+- [Upgrade or modify Zulip](../production/upgrade-or-modify.md)
 
 ## Monitoring
 
@@ -496,10 +141,54 @@ running Zulip with larger teams (especially >1000 users).
 Questions, concerns, and bug reports about this area of Zulip are very
 welcome!  This is an area we are hoping to improve.
 
-## Securing your Zulip server
+## Sections that have moved
 
-Zulip's security model is discussed in
-[a separate document](../production/security-model.md).
+These were once subsections of this page, but have since moved to
+dedicated pages; we preserve them here to avoid breaking old links.
+
+### Securing your Zulip server
+
+Moved to [Security Model](../production/security-model.md).
+
+### Upgrading
+
+Moved to [Upgrading to a release](../production/upgrade-or-modify.html#upgrading-to-a-release).
+
+### Upgrading from a Git repository
+
+Moved to [Upgrading from a Git
+repository](../production/upgrade-or-modify.html#upgrading-from-a-git-repository).
+
+### Upgrading the operating system
+
+Moved to [Upgrading the operating
+system](../production/upgrade-or-modify.html#upgrading-the-operating-system).
+
+## API and your Zulip URL
+
+To use the Zulip API with your Zulip server, you will need to use the
+API endpoint of e.g. `https://zulip.example.com/api`.  Our Python
+API example scripts support this via the
+`--site=https://zulip.example.com` argument.  The API bindings
+support it via putting `site=https://zulip.example.com` in your
+.zuliprc.
+
+Every Zulip integration supports this sort of argument (or e.g. a
+`ZULIP_SITE` variable in a zuliprc file or the environment), but this
+is not yet documented for some of the integrations (the included
+integration documentation on `/integrations` will properly document
+how to do this for most integrations).  We welcome pull requests for
+integrations that don't discuss this!
+
+Similarly, you will need to instruct your users to specify the URL
+for your Zulip server when using the Zulip desktop and mobile apps.
+
+## Memory leak mitigation
+
+As a measure to mitigate the impact of potential memory leaks in one
+of the Zulip daemons, the service automatically restarts itself
+every Sunday early morning.  See `/etc/cron.d/restart-zulip` for the
+precise configuration.
 
 ## Management commands
 
diff --git a/docs/production/mobile-push-notifications.md b/docs/production/mobile-push-notifications.md
index f83d28047e..66f95c09ef 100644
--- a/docs/production/mobile-push-notifications.md
+++ b/docs/production/mobile-push-notifications.md
@@ -21,7 +21,7 @@ follows:
 1. Uncomment the `PUSH_NOTIFICATION_BOUNCER_URL =
    'https://push.zulipchat.com'` line in your `/etc/zulip/settings.py`
    file (i.e. remove the `#` at the start of the line), and
-   [restart your Zulip server](../production/maintain-secure-upgrade.html#updating-settings).
+   [restart your Zulip server](../production/settings.html#making-changes).
    If you installed your Zulip server with a version older than 1.6,
    you'll need to add the line (it won't be there to uncomment).
 
diff --git a/docs/production/modifying-zulip.md b/docs/production/modifying-zulip.md
deleted file mode 100644
index 9fe030ca23..0000000000
--- a/docs/production/modifying-zulip.md
+++ /dev/null
@@ -1,210 +0,0 @@
-# Modifying or patching Zulip
-
-Zulip is 100% free and open source software, and you're welcome to
-modify it!  This page explains how to make and maintain modifications
-in a safe and convenient fashion.
-
-If you do modify Zulip and then report an issue you see in your
-modified version of Zulip, please be responsible about communicating
-that fact:
-
-* Ideally, you'd reproduce the issue in an unmodified version (e.g. on
-[chat.zulip.org](../contributing/chat-zulip-org.md) or
-[zulipchat.com](https://zulipchat.com)).
-* Where that is difficult or you think it's very unlikely your changes
-are related to the issue, just mention your changes in the issue report.
-
-## Making changes
-
-One way to modify Zulip is to just edit files under
-`/home/zulip/deployments/current` and then restart the server.  This
-can work OK for testing small changes to Python code or shell scripts.
-But we don't recommend this approach for maintaining changes because:
-
-* You cannot modify JavaScript, CSS, or other frontend files this way,
-  because we don't include them in editable form in our production
-  release tarballs (doing so would make our release tarballs much
-  larger without any runtime benefit).
-* You will need to redo your changes after you next upgrade your Zulip
-  server (or they will be lost).
-* You need to remember to restart the server or your changes won't
-  have effect.
-* Your changes aren't tracked, so mistakes can be hard to debug.
-
-Instead, we recommend the following GitHub-based workflow (see [our
-Git guide][git-guide] if you need a primer):
-
-* Decide where you're going to edit Zulip's code.  We recommend [using
-  the Zulip development environment](../development/overview.md) on
-  a desktop or laptop as it will make it extremely convenient for you
-  to test your changes without deploying them in production.  But if
-  your changes are small or you're OK with risking downtime, you don't
-  strictly need it; you just need an environment with Git installed.
-* **Important**.  Determine what Zulip version you're running on your
-  server.  You can check by inspecting `ZULIP_VERSION` in
-  `/home/zulip/deployments/current/version.py` (we'll use `2.0.4`
-  below).  If you apply your changes to the wrong version of Zulip,
-  it's likely to fail and potentially cause downtime.
-* [Fork and clone][fork-clone] the [zulip/zulip][] repository on
-  [GitHub](https://github.com).
-* Create a branch (named `acme-branch` below) containing your changes:
-
-```
-cd zulip
-git checkout -b acme-branch 2.0.4
-```
-
-* Use your favorite code editor to modify Zulip.
-* Commit your changes and push them to GitHub:
-
-```
-git commit -a
-
-# Use `git diff` to verify your changes are what you expect
-git diff 2.0.4 acme-branch
-
-# Push the changes to your GitHub fork
-git push origin +acme-branch
-```
-
-* Login to your Zulip server and configure and use
-[upgrade-zulip-from-git][] to install the changes; remember to
-configure `git_repo_url` to point to your fork on GitHub and run it as
-`upgrade-zulip-from-git acme-branch`.
-
-This workflow solves all of the problems described above: your change
-will be compiled and installed correctly (restarting the server), and
-your changes will be tracked so that it's convenient to maintain them
-across future Zulip releases.
-
-### Upgrading to future releases
-
-Eventually, you'll want to upgrade to a new Zulip release
-(e.g. `2.1.0` in this example).  If your changes were integrated into
-that Zulip release or are otherwise no longer needed, you can just use
-[upgrade-zulip][upgrade-zulip] as usual.  Otherwise, you'll need to
-update your branch by rebasing your changes (starting from a
-[clone][fork-clone] of the [zulip/zulip][] repository):
-
-```
-cd zulip
-git fetch --tags upstream
-git checkout acme-branch
-git rebase 2.1.0
-# Fix any errors or merge conflicts; see Zulip's Git Guide for advice
-
-# Use `git diff` to verify your changes are what you expect
-git diff 2.1.0 acme-branch
-
-git push origin +acme-branch
-```
-
-And then use [upgrade-zulip-from-git][] to install your updated
-branch, as before.
-
-### Making changes with docker-zulip
-
-If you are using [docker-zulip][], there are two things that are
-different from the above:
-
-* Because of how container images work, editing files directly is even
-  more precarious, because Docker is designed for working with
-  container images and may lose your changes.
-* Instead of running `upgrade-zulip-from-git`, you will need to use
-  the [docker upgrade workflow][docker-zulip-upgrade] to build a
-  container image based on your modified version of Zulip.
-
-[docker-zulip]: https://github.com/zulip/docker-zulip
-[docker-zulip-upgrade]: https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository
-
-## Applying changes from master
-
-If you are experiencing an issue that has already been fixed by the
-Zulip development community, and you'd like to get the fix now, you
-have a few options.  There are two possible ways you might get those
-fixes on your local Zulip server without waiting for an official release.
-
-### Applying a small change
-
-Many bugs have small/simple fixes.  In this case, you can use the Git
-workflow [described above](#making-changes), using:
-
-```
-git fetch upstream
-git cherry-pick abcd1234
-```
-
-instead of "making changes locally" (where `abcd1234` is the commit ID
-of the change you'd like).
-
-In general, we can't provide community support for issues caused by
-cherry-picking changes in this way.  There is a major exception to
-this rule.
-
-Zulip can be deployed in a wide variety of configurations and
-environments, and so we often merge fixes to bugs that we can
-reproduce in an automated test but have not directly reproduced in a
-production system.  In these cases, we'll ask the user(s) who reported
-the bug to apply the patch to their production system to verify the
-fix works for them.
-
-Generally, we'll only request this if we expect the fix in question to
-apply cleanly to the latest release without introducing regressions,
-and you can expect the Zulip community to be responsive in debugging
-any problems any caused by the patch.
-
-### Upgrading to master
-
-It's unsafe to backport arbitrary patches from master to an older
-version.  Common issues include:
-
-* Changes containing database migrations (new files under
-  `zerver/migrations/`), which includes most new major features.  We
-  don't support applying database migrations out of order.
-* Changes that are stacked on top of other changes to the same system.
-* Essentially any patch with hundreds of lines of changes.
-
-While it's possible to backport these sorts of changes, you're
-unlikely to succeed without help from the core team via a support
-contract.
-
-If you need an unreleased feature, the right path is usually to Zulip
-master using [upgrade-zulip-from-git][].  Before upgrading to master,
-make sure you understand:
-
-* The `master` branch is under very active development; dozens of new
-  changes are integrated into it on most days.  Master can have
-  thousands of changes not present in the latest release (all of which
-  will be included in our next release).  There are probably some
-  bugs.
-* That said we deploy master to chat.zulip.org and zulipchat.com on a
-  regular basis (often daily), so it's very important to the project
-  that it be stable.  Most regressions will be minor UX issues or be
-  fixed quickly.
-* The development community is very interested in helping debug issues
-  that arise when upgrading from the latest release to master, since
-  they provide us an opportunity to fix that category of issue before
-  our next major release.  (Much more so than we are in helping folks
-  debug other custom changes).  That said, we cannot make any
-  guarantees about how quickly we'll resolve an issue to folks without
-  a formal support contract.
-* We do not support downgrading from master to earlier versions, so if downtime
-  for your Zulip server is unacceptable, make sure you have a current
-  backup in case the upgrade fails.
-* Our changelog contains [draft release
-  notes](../overview/changelog.md) available listing major changes
-  since the last release.  The **Upgrade notes** section will always
-  be current, even if some new features aren't documented.
-
-## Contributing patches
-
-Zulip contains thousands of changes submitted by volunteer
-contributors like you.  If your changes are likely to be of useful to
-other organizations, consider [contributing
-them](../overview/contributing.md).
-
-[fork-clone]: ../git/cloning.html#get-zulip-code
-[upgrade-zulip-from-git]: ../production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
-[upgrade-zulip]: ../production/maintain-secure-upgrade.html#upgrading
-[git-guide]: ../git/index.md
-[zulip/zulip]: https://github.com/zulip/zulip/
diff --git a/docs/production/settings.md b/docs/production/settings.md
index 23ebf150e6..c86fec1b79 100644
--- a/docs/production/settings.md
+++ b/docs/production/settings.md
@@ -116,5 +116,5 @@ request; we love even small contributions, and we'd love to make the
 Zulip documentation cover everything anyone might want to know about
 running Zulip in production.
 
-Next: [Maintaining and upgrading Zulip in
-production](../production/maintain-secure-upgrade.md).
+Next: [Maintaining](../production/maintain-secure-upgrade.md) and
+[upgrading](../production/upgrade-or-modify.md) Zulip in production.
diff --git a/docs/production/upgrade-or-modify.md b/docs/production/upgrade-or-modify.md
new file mode 100644
index 0000000000..2a0b6379c5
--- /dev/null
+++ b/docs/production/upgrade-or-modify.md
@@ -0,0 +1,574 @@
+# Upgrade or modify Zulip
+
+This page explains how to upgrade, patch, or modify Zulip, including:
+
+- [Upgrading to a release](#upgrading-to-a-release)
+- [Upgrading from a git repository](#upgrading-from-a-git-repository)
+- [Troubleshooting and rollback](#troubleshooting-and-rollback)
+- [Preserving local changes to configuration files](#preserving-local-changes-to-configuration-files)
+- [Upgrading the operating system](#upgrading-the-operating-system)
+- [Modifying Zulip](#modifying-zulip)
+- [Applying changes from master](#applying-changes-from-master)
+
+## Upgrading to a release
+
+Note that there are additional instructions if you're [using
+docker-zulip][docker-upgrade], have [patched Zulip](#modifying-zulip),
+or have [modified Zulip-managed configuration
+files](#preserving-local-changes-to-configuration-files).  To upgrade
+to a new Zulip release:
+
+1. Download the appropriate release tarball from
+    <https://www.zulip.org/dist/releases/> You can download the latest
+    release with:
+
+    ```
+    wget https://www.zulip.org/dist/releases/zulip-server-latest.tar.gz
+    ```
+
+    You also have the option of upgrading Zulip [to a version in a Git
+    repository directly](#upgrading-from-a-git-repository) or creating
+    your own release tarballs from a copy of the [zulip.git
+    repository](https://github.com/zulip/zulip) using
+    `tools/build-release-tarball`.
+
+1. Login to your Zulip and run as root:
+
+    ```
+    /home/zulip/deployments/current/scripts/upgrade-zulip zulip-server-VERSION.tar.gz
+    ```
+
+    The upgrade process will:
+    * Shut down the Zulip service
+    * Run `apt-get upgrade`
+    * Run a `puppet apply`
+    * Run any database migrations
+    * Bring the Zulip service back up on the new version.
+
+Upgrading will result in brief downtime for the service, which should
+be under 30 seconds unless there is an expensive database migration
+involved (these will be documented in the [release
+notes](../overview/changelog.md), and usually can be avoided with
+some care).  If downtime is problematic for your organization,
+consider testing the upgrade on a
+[backup](../production/export-and-import.html#backups) in advance,
+doing the final upgrade at off hours, or buying a support contract.
+
+See the [troubleshooting guide](#troubleshooting-and-rollback) if you
+run into any issues or need to roll back the upgrade.
+
+## Upgrading from a git repository
+
+Zulip supports upgrading a production installation to any commit in a
+Git repository, which is great for [running pre-release changes from
+master](#applying-changes-from-master) or [maintaining a
+fork](#making-changes).  The process is simple:
+
+```
+# Upgrade to an official release
+/home/zulip/deployments/current/scripts/upgrade-zulip-from-git 1.8.1
+# Upgrade to a branch or other Git ref
+/home/zulip/deployments/current/scripts/upgrade-zulip-from-git master
+```
+
+Zulip will automatically fetch the relevant Git commit and upgrade to
+that version of Zulip.  Note that [downgrading to an older
+version](#upgrading-to-master) using this process won't work.
+
+By default, this uses the main upstream Zulip server repository, but
+you can configure any other Git repository by adding a section like
+this to `/etc/zulip/zulip.conf`:
+
+```
+[deployment]
+git_repo_url = https://github.com/zulip/zulip.git
+```
+
+See also our documentation on [upgrading
+docker-zulip](https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository).
+
+## Troubleshooting and rollback
+
+See also the general Zulip server [troubleshooting
+guide](../production/troubleshooting.md).
+
+The upgrade scripts are idempotent, so there's no harm in trying again
+after resolving an issue.  The most common causes of errors are:
+
+* Networking issues (e.g. your Zulip server doesn't have reliable
+  Internet access or needs a proxy setup).  Fix the networking issue
+  and try again.
+* Especially when using `upgrade-zulip-from-git`, systems with the
+  minimal RAM for running Zulip can run into out-of-memory issues
+  during the upgrade process (generally `tools/webpack` is the step
+  that fails).  You can get past this by shutting down the Zulip
+  server with `supervisorctl stop all` to free up RAM before running
+  the upgrade process.
+
+Useful logs are available in a few places:
+* The Zulip upgrade scripts log all output to
+  `/var/log/zulip/upgrade.log`.
+* The Zulip server logs all Internal Server Errors to
+  `/var/log/zulip/errors.log`.
+
+If you need help and don't have a support contract, you can visit
+[#production
+help](https://chat.zulip.org/#narrow/stream/31-production-help) in the
+[Zulip development community
+server](../contributing/chat-zulip-org.md) for best-effort help.
+Please include the relevant error output from the above logs in a
+[markdown code
+block](https://zulipchat.com/help/format-your-message-using-markdown#code)
+in any reports.
+
+### Rolling back to a prior version
+
+This rollback process is primarily useful for minor releases
+(e.g. `2.0.3` to `2.0.6`); a more complicated process is required to
+rollback database migrations before downgrading to an older major
+release.
+
+The Zulip upgrade process works by creating a new deployment under
+`/home/zulip/deployments/` containing a complete copy of the Zulip server code,
+and then moving the symlinks at `/home/zulip/deployments/{current,last,next}`
+as part of the upgrade process.
+
+This means that if the new version isn't working,
+you can quickly downgrade to the old version by running
+`/home/zulip/deployments/last/scripts/restart-server`, or to an
+earlier previous version by running
+`/home/zulip/deployments/DATE/scripts/restart-server`.  The
+`restart-server` script stops any running Zulip server, and starts
+the version corresponding to the `restart-server` path you call.
+
+## Preserving local changes to configuration files
+
+```eval_rst
+.. warning::
+    If you have modified configuration files installed by
+    Zulip (e.g. the nginx configuration), the Zulip upgrade process will
+    overwrite your configuration when it does the `puppet apply`.
+```
+
+You can test whether this will happen assuming no upstream changes to
+the configuration using `scripts/zulip-puppet-apply` (without the
+`-f` option), which will do a test puppet run and output and changes
+it would make. Using this list, you can save a copy of any files
+that you've modified, do the upgrade, and then restore your
+configuration.
+
+That said, Zulip's configuration files are designed to be flexible
+enough for a wide range of installations, from a small self-hosted
+system to Zulip Cloud.  Before making local changes to a configuration
+file, first check whether there's an option supported by
+`/etc/zulip/zulip.conf` for the customization you need.  And if you
+need to make local modifications, please report the issue so that we
+can make the Zulip puppet configuration flexible enough to handle your
+setup.
+
+### nginx configuration changes
+
+If you need to modify Zulip's `nginx` configuration, we recommend
+first attempting to add configuration to `/etc/nginx/conf.d` or
+`/etc/nginx/zulip-include/app.d`; those directories are designed for
+custom configuration.
+
+## Upgrading the operating system
+
+When you upgrade the operating system on which Zulip is installed
+(E.g. Ubuntu 14.04 Trusty to Ubuntu 16.04 Xenial), you need to take
+some additional steps to update your Zulip installation, documented
+below.
+
+The steps are largely the same for the various OS upgrades aside from
+the versions of postgres, so you should be able to adapt these
+instructions for other supported platforms.
+
+### Upgrading from Ubuntu 14.04 Trusty to 16.04 Xenial
+
+1. First, as the Zulip user, stop the Zulip server and run the following
+to back up the system:
+
+    ```
+    supervisorctl stop all
+    /home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
+    ```
+
+2. Switch to the root user and upgrade the operating system using the
+OS's standard tooling.  E.g. for Ubuntu, this means running
+`do-release-upgrade` and following the prompts until it completes
+successfully:
+
+    ```
+    sudo -i # Or otherwise get a root shell
+    do-release-upgrade
+    ```
+
+    When `do-release-upgrade` asks you how to upgrade configuration
+    files for services that Zulip manages like `redis`, `postgres`,
+    `nginx`, and `memcached`, the best choice is `N` to keep the
+    currently installed version.  But it's not important; the next
+    step will re-install Zulip's configuration in any case.
+
+3. As root, upgrade the database installation and OS configuration to
+match the new OS version:
+
+    ```
+    apt remove upstart -y
+    /home/zulip/deployments/current/scripts/zulip-puppet-apply -f
+    pg_dropcluster 9.5 main --stop
+    systemctl stop postgresql
+    pg_upgradecluster -m upgrade 9.3 main
+    pg_dropcluster 9.3 main
+    apt remove postgresql-9.3
+    systemctl start postgresql
+    service memcached restart
+    ```
+
+4. At this point, you are now running the version of postgres that
+comes with the new Ubuntu version.  Finally, we need to reinstall the
+current version of Zulip, which among other things will recompile
+Zulip's Python module dependencies for your new version of Python:
+
+    ```
+    rm -rf /srv/zulip-venv-cache/*
+    /home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
+        /home/zulip/deployments/current/ --ignore-static-assets
+    ```
+
+That last command will finish by restarting your Zulip server; you
+should now be able to navigate to its URL and confirm everything is
+working correctly.
+
+### Upgrading from Ubuntu 16.04 Xenial to 18.04 Bionic
+
+1. First, as the Zulip user, stop the Zulip server and run the following
+to back up the system:
+
+    ```
+    supervisorctl stop all
+    /home/zulip/deployments/current/manage.py backup --output=/home/zulip/release-upgrade.backup.tar.gz
+    ```
+
+2. Switch to the root user and upgrade the operating system using the
+OS's standard tooling.  E.g. for Ubuntu, this means running
+`do-release-upgrade` and following the prompts until it completes
+successfully:
+
+    ```
+    sudo -i # Or otherwise get a root shell
+    do-release-upgrade
+    ```
+
+    When `do-release-upgrade` asks you how to upgrade configuration
+    files for services that Zulip manages like `redis`, `postgres`,
+    `nginx`, and `memcached`, the best choice is `N` to keep the
+    currently installed version.  But it's not important; the next
+    step will re-install Zulip's configuration in any case.
+
+3. As root, upgrade the database installation and OS configuration to
+match the new OS version:
+
+    ```
+    touch /usr/share/postgresql/10/pgroonga_setup.sql.applied
+    /home/zulip/deployments/current/scripts/zulip-puppet-apply -f
+    pg_dropcluster 10 main --stop
+    systemctl stop postgresql
+    pg_upgradecluster 9.5 main
+    pg_dropcluster 9.5 main
+    apt remove postgresql-9.5
+    systemctl start postgresql
+    systemctl restart memcached
+    ```
+
+4. At this point, you are now running the version of postgres that
+comes with the new Ubuntu version.  Finally, we need to reinstall the
+current version of Zulip, which among other things will recompile
+Zulip's Python module dependencies for your new version of Python:
+
+    ```
+    rm -rf /srv/zulip-venv-cache/*
+    /home/zulip/deployments/current/scripts/lib/upgrade-zulip-stage-2 \
+        /home/zulip/deployments/current/ --ignore-static-assets
+    ```
+
+That last command will finish by restarting your Zulip server; you
+should now be able to navigate to its URL and confirm everything is
+working correctly.
+
+
+## Modifying Zulip
+
+Zulip is 100% free and open source software, and you're welcome to
+modify it!  This section explains how to make and maintain
+modifications in a safe and convenient fashion.
+
+If you do modify Zulip and then report an issue you see in your
+modified version of Zulip, please be responsible about communicating
+that fact:
+
+* Ideally, you'd reproduce the issue in an unmodified version (e.g. on
+[chat.zulip.org](../contributing/chat-zulip-org.md) or
+[zulipchat.com](https://zulipchat.com)).
+* Where that is difficult or you think it's very unlikely your changes
+are related to the issue, just mention your changes in the issue report.
+
+If you're looking to modify Zulip by applying changes developed by the
+Zulip core team and merged into master, skip to [this
+section](#applying-changes-from-master).
+
+## Making changes
+
+One way to modify Zulip is to just edit files under
+`/home/zulip/deployments/current` and then restart the server.  This
+can work OK for testing small changes to Python code or shell scripts.
+But we don't recommend this approach for maintaining changes because:
+
+* You cannot modify JavaScript, CSS, or other frontend files this way,
+  because we don't include them in editable form in our production
+  release tarballs (doing so would make our release tarballs much
+  larger without any runtime benefit).
+* You will need to redo your changes after you next upgrade your Zulip
+  server (or they will be lost).
+* You need to remember to restart the server or your changes won't
+  have effect.
+* Your changes aren't tracked, so mistakes can be hard to debug.
+
+Instead, we recommend the following GitHub-based workflow (see [our
+Git guide][git-guide] if you need a primer):
+
+* Decide where you're going to edit Zulip's code.  We recommend [using
+  the Zulip development environment](../development/overview.md) on
+  a desktop or laptop as it will make it extremely convenient for you
+  to test your changes without deploying them in production.  But if
+  your changes are small or you're OK with risking downtime, you don't
+  strictly need it; you just need an environment with Git installed.
+* **Important**.  Determine what Zulip version you're running on your
+  server.  You can check by inspecting `ZULIP_VERSION` in
+  `/home/zulip/deployments/current/version.py` (we'll use `2.0.4`
+  below).  If you apply your changes to the wrong version of Zulip,
+  it's likely to fail and potentially cause downtime.
+* [Fork and clone][fork-clone] the [zulip/zulip][] repository on
+  [GitHub](https://github.com).
+* Create a branch (named `acme-branch` below) containing your changes:
+
+```
+cd zulip
+git checkout -b acme-branch 2.0.4
+```
+
+* Use your favorite code editor to modify Zulip.
+* Commit your changes and push them to GitHub:
+
+```
+git commit -a
+
+# Use `git diff` to verify your changes are what you expect
+git diff 2.0.4 acme-branch
+
+# Push the changes to your GitHub fork
+git push origin +acme-branch
+```
+
+* Login to your Zulip server and configure and use
+[upgrade-zulip-from-git][] to install the changes; remember to
+configure `git_repo_url` to point to your fork on GitHub and run it as
+`upgrade-zulip-from-git acme-branch`.
+
+This workflow solves all of the problems described above: your change
+will be compiled and installed correctly (restarting the server), and
+your changes will be tracked so that it's convenient to maintain them
+across future Zulip releases.
+
+### Upgrading to future releases
+
+Eventually, you'll want to upgrade to a new Zulip release
+(e.g. `2.1.0` in this example).  If your changes were integrated into
+that Zulip release or are otherwise no longer needed, you can just use
+[upgrade as usual](#upgrading-to-a-release).  Otherwise, you'll need
+to update your branch by rebasing your changes (starting from a
+[clone][fork-clone] of the [zulip/zulip][] repository):
+
+If you want to keep your modifications, you'll need to
+update your branch by rebasing your changes (starting from a
+[clone][fork-clone] of the [zulip/zulip][] repository):
+
+```
+cd zulip
+git fetch --tags upstream
+git checkout acme-branch
+git rebase 2.1.0
+# Fix any errors or merge conflicts; see Zulip's Git Guide for advice
+
+# Use `git diff` to verify your changes are what you expect
+git diff 2.1.0 acme-branch
+
+git push origin +acme-branch
+```
+
+And then use [upgrade-zulip-from-git][] to install your updated
+branch, as before.
+
+### Making changes with docker-zulip
+
+If you are using [docker-zulip][], there are two things that are
+different from the above:
+
+* Because of how container images work, editing files directly is even
+  more precarious, because Docker is designed for working with
+  container images and may lose your changes.
+* Instead of running `upgrade-zulip-from-git`, you will need to use
+  the [docker upgrade workflow][docker-zulip-upgrade] to build a
+  container image based on your modified version of Zulip.
+
+[docker-zulip]: https://github.com/zulip/docker-zulip
+[docker-zulip-upgrade]: https://github.com/zulip/docker-zulip#upgrading-from-a-git-repository
+
+## Applying changes from master
+
+If you are experiencing an issue that has already been fixed by the
+Zulip development community, and you'd like to get the fix now, you
+have a few options.  There are two possible ways you might get those
+fixes on your local Zulip server without waiting for an official release.
+
+### Applying a small change
+
+Many bugs have small/simple fixes.  In this case, you can use the Git
+workflow [described above](#making-changes), using:
+
+```
+git fetch upstream
+git cherry-pick abcd1234
+```
+
+instead of "making changes locally" (where `abcd1234` is the commit ID
+of the change you'd like).
+
+In general, we can't provide support for issues caused by
+cherry-picking arbitrary commits if the issues don't also affect
+master or an official release.  However, there is a major exception to
+this rule.
+
+Zulip can be deployed in a wide variety of configurations and
+environments, and so we often merge fixes to bugs that we can
+reproduce in an automated test but have not directly reproduced in a
+production system.  In these cases, we'll ask the user(s) who reported
+the bug to apply the patch to their production system to verify the
+fix works for them.
+
+Generally, we'll only request this if we expect the fix in question to
+apply cleanly to the latest release without introducing regressions,
+and you can expect the Zulip community to be responsive in debugging
+any problems any caused by a patch we asked you to apply.
+
+### Upgrading to master
+
+It's unsafe to backport arbitrary patches from master to an older
+version.  Common issues include:
+
+* Changes containing database migrations (new files under
+  `zerver/migrations/`), which includes most new features.  We
+  don't support applying database migrations out of order.
+* Changes that are stacked on top of other changes to the same system.
+* Essentially any patch with hundreds of lines of changes.
+
+While it's possible to backport these sorts of changes, you're
+unlikely to succeed without help from the core team via a support
+contract.
+
+If you need an unreleased feature, the best path is usually to Zulip
+master using [upgrade-zulip-from-git][].  Before upgrading to master,
+make sure you understand:
+
+* The `master` branch is under very active development; dozens of new
+  changes are integrated into it on most days.  Master can have
+  thousands of changes not present in the latest release (all of which
+  will be included in our next release).  There are probably some
+  bugs.
+* That said we deploy master to chat.zulip.org and zulipchat.com on a
+  regular basis (often daily), so it's very important to the project
+  that it be stable.  Most regressions will be minor UX issues or be
+  fixed quickly.
+* The development community is very interested in helping debug issues
+  that arise when upgrading from the latest release to master, since
+  they provide us an opportunity to fix that category of issue before
+  our next major release.  (Much more so than we are in helping folks
+  debug other custom changes).  That said, we cannot make any
+  guarantees about how quickly we'll resolve an issue to folks without
+  a formal support contract.
+* We do not support downgrading from master to earlier versions, so if downtime
+  for your Zulip server is unacceptable, make sure you have a current
+  backup in case the upgrade fails.
+* Our changelog contains [draft release
+  notes](../overview/changelog.md) available listing major changes
+  since the last release.  The **Upgrade notes** section will always
+  be current, even if some new features aren't documented.
+
+### Applying system updates
+
+The Zulip upgrade script will automatically run `apt-get update` and
+then `apt-get upgrade`, to make sure you have any new versions of
+dependencies (this will also update system packages).  We assume that
+you will install security updates from `apt` regularly, according to
+your usual security practices for a production server.
+
+If you'd like to minimize downtime when installing a Zulip server
+upgrade, you may want to do an `apt-get upgrade` (and then restart the
+server and check everything is working) before running the Zulip
+upgrade script.
+
+There's one `apt` package to be careful about: upgrading `postgresql`
+while the server is running may result in an outage (basically,
+`postgresql` might stop accepting new queries but refuse to shut down
+while waiting for connections from the Zulip server to shut down).
+While this only happens sometimes, it can be hard to fix for someone
+who isn't comfortable managing a `postgresql` database [1].  You can
+avoid that possibility with the following procedure (run as root):
+
+```
+apt-get update
+supervisorctl stop all
+apt-get upgrade -y
+supervisorctl start all
+```
+
+[1] If this happens to you, just stop the Zulip server, restart
+postgres, and then start the Zulip server again, and you'll be back in
+business.
+
+#### Disabling unattended upgrades
+
+**Important**: We recommend that you
+[disable Ubuntu's unattended-upgrades][disable-unattended-upgrades],
+and instead install apt upgrades manually.  With unattended upgrades
+enabled, the moment a new Postgres release is published, your Zulip
+server will have its postgres server upgraded (and thus restarted).
+
+When one of the services Zulip depends on (postgres, memcached, redis,
+rabbitmq) is restarted, that services will disconnect everything using
+them (like the Zulip server), and every operation that Zulip does
+which uses that service will throw an exception (and send you an error
+report email).  These apparently "random errors" can be confusing and
+might cause you to worry incorrectly about the stability of the Zulip
+software, which in fact the problem is that Ubuntu automatically
+upgraded and then restarted key Zulip dependencies.
+
+Instead, we recommend installing updates for these services manually,
+and then restarting the Zulip server with
+`/home/zulip/deployments/current/scripts/restart-server` afterwards.
+
+[disable-unattended-upgrades]: https://linoxide.com/ubuntu-how-to/enable-disable-unattended-upgrades-ubuntu-16-04/
+
+## Contributing patches
+
+Zulip contains thousands of changes submitted by volunteer
+contributors like you.  If your changes are likely to be of useful to
+other organizations, consider [contributing
+them](../overview/contributing.md).
+
+[fork-clone]: ../git/cloning.html#get-zulip-code
+[upgrade-zulip-from-git]: #upgrading-from-a-git-repository
+[upgrade-zulip]: #upgrading
+[git-guide]: ../git/index.md
+[zulip/zulip]: https://github.com/zulip/zulip/
+[docker-upgrade]: https://github.com/zulip/docker-zulip#upgrading-the-zulip-container
diff --git a/templates/zerver/help/import-from-gitter.md b/templates/zerver/help/import-from-gitter.md
index 29aaaa12ca..ce9f3b1940 100644
--- a/templates/zerver/help/import-from-gitter.md
+++ b/templates/zerver/help/import-from-gitter.md
@@ -97,4 +97,4 @@ to mark the appropriate users as administrators.
   [issue mentions](https://gitter.zendesk.com/hc/en-us/articles/200176692-Issue-and-Pull-Request-mentions)
   aren't translated into anything yet.
 
-[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
+[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
diff --git a/templates/zerver/help/import-from-hipchat.md b/templates/zerver/help/import-from-hipchat.md
index c4b382fd07..8392d2e249 100644
--- a/templates/zerver/help/import-from-hipchat.md
+++ b/templates/zerver/help/import-from-hipchat.md
@@ -130,7 +130,7 @@ root domain. Replace the last line above with the following, after replacing
 
 {!import-login.md!}
 
-[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
+[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
 
 ## Caveats
 
@@ -152,5 +152,5 @@ rooms.  You can pick one of the following options for handling this:
   access token via `--token=abcd1234` in `manage.py convert_hipchat_data`
   (or include it in your request, if importing into Zulip Cloud).
 
-[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
+[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
 [hipchat-api-tokens]: https://developer.atlassian.com/server/hipchat/hipchat-rest-api-access-tokens/
diff --git a/templates/zerver/help/import-from-mattermost.md b/templates/zerver/help/import-from-mattermost.md
index d5ac76d98a..5634b30f88 100644
--- a/templates/zerver/help/import-from-mattermost.md
+++ b/templates/zerver/help/import-from-mattermost.md
@@ -170,7 +170,7 @@ root domain. Replace the last line above with the following, after replacing
 
 {!import-login.md!}
 
-[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
+[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
 
 ## Caveats
 
@@ -188,4 +188,4 @@ messages with a specific Mattermost team.  For that reason, the import
 tool will only import private messages for data export archives
 containing a single Mattermost team.
 
-[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
+[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository
diff --git a/templates/zerver/help/import-from-slack.md b/templates/zerver/help/import-from-slack.md
index b167890886..8b3a5dde84 100644
--- a/templates/zerver/help/import-from-slack.md
+++ b/templates/zerver/help/import-from-slack.md
@@ -97,4 +97,4 @@ root domain. Replace the last line above with the following, after replacing
 
 - The "joined #channel_name" messages are not imported.
 
-[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/maintain-secure-upgrade.html#upgrading-from-a-git-repository
+[upgrade-zulip-from-git]: https://zulip.readthedocs.io/en/latest/production/upgrade-or-modify.html#upgrading-from-a-git-repository