help: Document process for changing organization URL.

templates/zerver/help/change-organization-url.md

@@ -0,0 +1,30 @@
+# Change organization URL
+
+Zulip supports changing the URL for an organization.  Changing the
+organization URL is a disruptive operation for users:
+
+* Users will be logged out of existing sessions on the web, mobile and
+  desktop apps and need to login again.
+* Any [API clients](/api) or [integrations](/integrations) will need
+  to be updated to point to the new organization URL.
+
+We recommend using a [wildcard
+mention](/help/mention-a-user-or-group#mention-everyone-on-a-stream)
+in an announcement stream to notify users that they need to update
+their clients.
+
+If you're using Zulip Cloud (E.g. `https://example.zulipchat.com`),
+you can request a change by emailing support@zulip.com.
+
+## Self-hosting
+
+If you're self-hosting, you can change the root domain if your server
+by changing the `EXTERNAL_HOST` [setting][zulip-settings].  If you're
+[hosting multiple organizations][zulip-multiple-organizations] and
+want to change the subdomain for one of them, you can use
+`do_realm_change_subdomain(realm, "new_subdomain")` in a [management
+shell][management-shell].
+
+[zulip-settings]: https://zulip.readthedocs.io/en/stable/production/settings.html
+[zulip-multiple-organizations]: https://zulip.readthedocs.io/en/stable/production/multiple-organizations.html
+[management-shell]: https://zulip.readthedocs.io/en/stable/production/management-commands.html#manage-py-shell

templates/zerver/help/include/sidebar_index.md

@@ -113,6 +113,7 @@
 * [Roles and permissions](/help/roles-and-permissions)
 * [Set the default language for new users](/help/change-the-default-language-for-your-organization)
 * [Export your organization](/help/export-your-organization)
+* [Change organization URL](/help/change-organization-url)
 * [Deactivate your organization](/help/deactivate-your-organization)
 * [GDPR Compliance](/help/gdpr-compliance)
 

tools/linter_lib/custom_check.py

@@ -717,6 +717,7 @@ help_markdown_rules = RuleList(
          },
         {'pattern': r'\b[rR]ealm[s]?\b',
          'include_only': {'templates/zerver/help/'},
+         'exclude': {'templates/zerver/help/change-organization-url.md'},
          'good_lines': ['Organization', 'deactivate_realm', 'realm_filter'],
          'bad_lines': ['Users are in a realm', 'Realm is the best model'],
          'description': "Realms are referred to as Organizations in user-facing docs."},