settings: Rework how push notifications service is configured.

Instead of the PUSH_NOTIFICATIONS_BOUNCER_URL and
SUBMIT_USAGE_STATISTICS settings, we want servers to configure
individual ZULIP_SERVICE_* settings, while maintaining backward
compatibility with the old settings. Thus, if all the new
ZULIP_SERVICE_* are at their default False value, but the legacy
settings are activated, they need to be translated in computed_settings
to the modern way.

docs/overview/changelog.md

@@ -191,6 +191,29 @@ log][commit-log] for an up-to-date list of all changes.
   to give time to potentially reconfigure which channel to use. You can
   override the delay by running `./manage.py send_zulip_update_announcements --skip-delay`
   once you've done any necessary configuration updates.
+- We've reworked how Zulip's mobile push notifications service is
+  configured to be easier to understand, more extensible, and avoid
+  hardcoding URLs unnecessarily. The old settings names are fully
+  supported with identical behavior, so no action is required before
+  upgrading.
+
+  Once you've upgraded, while you're [updating your settings.py
+  documentation][update-settings-docs], we recommend updating
+  `/etc/zulip/settings.py` to use the modern settings names: Replacing
+  `PUSH_NOTIFICATIONS_BOUNCER_URL = "https://push.zulipchat.com"` with
+  `ZULIP_SERVICE_PUSH_NOTIFICATIONS = True` and renaming
+  `SUBMIT_USAGE_STATISTICS` to
+  `ZULIP_SERVICE_SUBMIT_USAGE_STATISTICS`, if you have either of those
+  settings enabled. It's important not to set both the old and new
+  settings: The modern settings will be ignored if the legacy ones are
+  present.
+
+  The one minor functional change in this restructuring is that it is
+  now possible to configure sharing usage statistics with the Zulip
+  developers without attempting to send mobile push notifications via
+  the service, by setting `ZULIP_SERVICE_PUSH_NOTIFICATIONS = False`
+  and `ZULIP_SERVICE_SUBMIT_USAGE_STATISTICS=True`.
+
 - The Zulip server now contains a KaTeX server worker, designed to
   make bulk-rendering LaTeX efficient. It has minimal memory
   footprint, but can be disabled using the `katex_server` [deployment

docs/production/mobile-push-notifications.md

@@ -1,41 +1,57 @@
 # Mobile push notification service
 
-Zulip's iOS and Android [mobile apps](https://zulip.com/apps/) support receiving
-push notifications from Zulip servers to let users know when new messages have
-arrived. This is an important feature for having a great mobile app experience.
+Zulip's iOS and Android [mobile apps](https://zulip.com/apps/) support
+receiving push notifications from Zulip servers to notify users when
+new messages have arrived. This is an important feature for having a
+great mobile app experience.
 
-To set up mobile push notifications, you will need to register your Zulip server
-with the Zulip mobile push notification service. This service will forward push
-notifications generated by your server to users' mobile apps.
+The security model for mobile push notifications does not allow
+self-hosted Zulip servers to directly send mobile notifications to the
+Zulip mobile apps. The Zulip mobile push notification service solves
+this problem by forwarding mobile push notifications generated by your
+server to the Zulip mobile apps.
 
-## How to sign up
+## Signing up
 
 You can enable the mobile push notification service for your Zulip server as
 follows:
 
+1. Check that your [server
+   version](https://zulip.com/help/view-zulip-version) is has Zulip
+   Server 9.0 or greater. For older versions, see the [Zulip 8.x
+   documentation](https://zulip.readthedocs.io/en/8.4/production/mobile-push-notifications.html).
+
 1. Make sure your server has outgoing HTTPS access to the public Internet. If
    that is restricted by a proxy, you will need to [configure Zulip to use your
    outgoing HTTP proxy](deployment.md#customizing-the-outgoing-http-proxy)
    first.
 
+1. Set `ZULIP_SERVICE_PUSH_NOTIFICATIONS = True` in your
+   `/etc/zulip/settings.py` file. The [comments in
+   settings.py][update-settings-docs] should contain this line,
+   commented out with a `# `. Delete the `# ` at the start of the line
+   to enable the setting.
+
 1. Decide whether to share usage statistics with the Zulip team.
 
    By default, Zulip installations using the Mobile Push Notification
    Service submit additional usage statistics that help Zulip's
    maintainers allocate resources towards supporting self-hosted
-   installations ([details](#uploading-usage-statistics)). You can
-   disable submitting usage statistics now or at any time by setting
-   `SUBMIT_USAGE_STATISTICS=False` in `/etc/zulip/settings.py`.
+   installations ([details](#uploading-usage-statistics)).
+
+   You can disable submitting usage statistics now or at any time by
+   setting `ZULIP_SERVICE_SUBMIT_USAGE_STATISTICS=False` in
+   `/etc/zulip/settings.py` (the template contains a convenient
+   commented line that you can uncomment).
 
    Note that all systems using the service upload [basic
    metadata](#uploading-basic-metadata) about the organizations hosted
    by the installation.
 
-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](settings.md#making-changes).
+   [update-settings-docs]: ../production/upgrade.md#updating-settingspy-inline-documentation
+
+1. [Restart your Zulip server](settings.md#making-changes) so that
+   your configuration changes take effect.
 
 1. Run the registration command. If you installed Zulip directly on the server
    (without Docker), run as root:
@@ -248,7 +264,7 @@ Push Notifications Service itself.
 By default, Zulip installations that register for the Mobile Push
 Notifications Service upload the following usage statistics. You can
 disable these uploads any time by setting
-`SUBMIT_USAGE_STATISTICS=False` in `/etc/zulip/settings.py`.
+`ZULIP_SERVICE_SUBMIT_USAGE_STATISTICS=False` in `/etc/zulip/settings.py`.
 
 - Totals for messages sent and read with subtotals for various
   combinations of clients and integrations.
@@ -261,8 +277,8 @@ statistics.
 
 When enabled, usage statistics are submitted via an hourly cron
 job. If you'd like to access plan management immediately after
-enabling `SUBMIT_USAGE_STATISTICS=True` on a pre-8.0 Zulip server, you
-can run the analytics job manually via:
+enabling `SUBMIT_USAGE_STATISTICS=True` (the legacy form of this setting)
+on a pre-8.0 Zulip server, you can run the analytics job manually via:
 
 ```
 /home/zulip/deployments/current/manage.py update_analytics_counts
@@ -325,7 +341,7 @@ registration.
    ```
 
 1. Comment out the
-   `PUSH_NOTIFICATION_BOUNCER_URL = 'https://push.zulipchat.com'` line
+   `ZULIP_SERVICE_PUSH_NOTIFICATIONS = True` line
    in your `/etc/zulip/settings.py` file (i.e., add `# ` at the
    start of the line), and [restart your Zulip
    server](settings.md#making-changes).