Merge branch 'timezones' into 'master'

Add section about MySQL Timezones

See merge request !53

docs/general/requirements.md

@@ -235,7 +235,9 @@ Additional URL parameters may be added to support [MySQL with TLS](mysql_tls.md)
    skip-log-bin
   ```
 
-#### MySQL Time
+### MySQL Time
+
+#### Synchronization {:#mysql-time-sync}
 
 CiviCRM performs various operations based on dates and times – for example, deactivating expired records or triggering scheduled reminders. To perform these operations correctly, the dates and times reported by PHP and MySQL should match. If the dates or times are mismatched, then one or more of the following may be the problem:
 
@@ -243,9 +245,74 @@ CiviCRM performs various operations based on dates and times – for example, de
 * PHP, MySQL, and/or the operating system may be configured to use different default timezones. Verify the configuration of each.
 * The content management system (Drupal, Joomla, or WordPress) or one of its plugins may manipulate the timezone settings without informing CiviCRM's. You may wish to post to [Stack Exchange](https://civicrm.stackexchange.com/) or [Mattermost](https://chat.civicrm.org) about your problem. Please include any available details about the timezone settings in the operating system, PHP, MySQL, and the CMS; if you have any special CMS plugins or configuration options which may affect timezones, please report them.
 
-#### MySQL/PHP Time Mismatch Warning - WordPress
+!!! tip "WordPress Settings"
+
+    If you get a MySQL/PHP mismatch warning, under `Settings > General` set the timezone to a City, not UTC offset.  For example, use `London` not `UTC+0`.
+
+#### Timezones {:#mysql-timezones}
+
+To support full and consistent display of timestamps, the MySQL server requires timezone data. Many servers include this data by default, but others require you to load it.
+
+??? info "Survey of MySQL Servers and Timezone Support"
+
+    <!-- Sorted by `Status,Environment` -->
+
+    | Status | Environment | Comment |
+    | -- |  -- |  -- |
+    | ✅ | CiviHosting | |
+    | ✅ | Digital Ocean | Specifically tested w/[managed MySQL 8.0](https://www.digitalocean.com/products/managed-databases-mysql) |
+    | ✅ | Docker `mysql` | Specifically tested w/[8.0, 8.0-oracle, and 5.7](https://hub.docker.com/_/mysql) |
+    | ✅ | Docker `mariadb` | Specifically tested w/[10.3 and 10.4](https://hub.docker.com/_/mariadb) |
+    | ✅ | Google Cloud SQL | Specifically tested w/5.6. Warning from docs: ["not guaranteed to provide up-to-date time settings"](https://cloud.google.com/sql/docs/mysql/known-issues) |
+    | 🛠 | Azure Database | Use [`az_load_timezone()`](https://docs.microsoft.com/en-us/azure/mysql/howto-server-parameters#working-with-the-time-zone-parameter)  |
+    | 🛠 | CentOS MariaDB/MySQL | Use `mysql_tzinfo_to_sql` |
+    | 🛠 | cPanel/WHM (with root access) | Use `mysql_tzinfo_to_sql` |
+    | 🛠 | Debian/Ubuntu MariaDB/MySQL | Use `mysql_tzinfo_to_sql` |
+    | 🛠 | Nix MariaDB/MySQL | Use `mysql_tzinfo_to_sql` |
+    | ❓ | Amazon RDS | Needs testing/clarification. There are old google-cached forum posts which imply gradual evolution toward support. The current ["Local time zone" page](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/CHAP_MySQL.html#MySQL.Concepts.LocalTimeZone) seems to affirm, so probably ✅ ... but the docs don't specifically mention session-scoped timezones. |
+    | ❓ | cPanel/WHM (without root access) | Needs testing/clarification. If you lack access to `mysql_tzinfo_sql` (SSH) but have other ways to perform MySQL administration, then you may be able to to load [pre-generated MySQL timezone data](https://github.com/civicrm/tzdata-mysql). Key question is whether you have MySQL admin rights. |
+    | ❓ | Pantheon | Needs testing/clarification. |
+    | ❓ | WP Engine | Needs testing/clarification. |
+
+    Definitions:
+
+    * (✅) Already support MySQL timezones
+    * (🛠) Can support MySQL timezones, with extra setup
+    * (❓) Status is not certain
+    * (🛑) Cannot support MySQL timezones
+
+To determine if your server currently supports timezones, you can run a test with the `CONVERT_TZ()` function.
+
+```sql
+mysql> SELECT CONVERT_TZ("2001-02-03 04:05:00", "GMT", "America/New_York");
++--------------------------------------------------------------+
+| CONVERT_TZ("2001-02-03 04:05:00", "GMT", "America/New_York") |
++--------------------------------------------------------------+
+| 2001-02-02 23:05:00                                          |
++--------------------------------------------------------------+
+```
+
+If this doesn't perform a proper conversion, then you probably need to load the timezone data.
+
+* On a self-hosted instance of MySQL or MariaDB, the standard technique is to run [`mysql_tzinfo_to_sql`](https://dev.mysql.com/doc/refman/8.0/en/mysql-tzinfo-to-sql.html).
+* If you cannot run `mysql_tzinfo_to_sql` but have administrative access through another medium, you may load the [pre-generated MySQL timezone data](https://github.com/civicrm/tzdata-mysql/tree/master/sql).
+  Be sure to load the appropriate SQL file into the database named `mysql`.
+* Some managed hosts require their own process. For example, "Azure Database" has a special procedure ([`az_load_timezone()`](https://docs.microsoft.com/en-us/azure/mysql/howto-server-parameters#working-with-the-time-zone-parameter)).
+  For managed hosts, you may need to consult their documentation or inquire with support.
+
+??? info "Global organizations and service-providers should consider automation."
+
+    Timezone definitions change, albeit infrequently.  For example, in 1996, Mexico adopted Daylight Savings Time (for most of its timezones); then,
+    in 2022, they dropped DST.  For computer-based clocks supporting users in Mexico, those changes require an update to the timezone data.  But it's
+    rare -- for Mexico, that represents two major changes (circa 1996 and 2022) over the span of 26 years.
+
+    The significance of timezone change is circumstantial. Compare:
 
-If you get a MySQL/PHP mismatch warning, under `Settings > General` set the timezone to a City, not UTC offset.  For example, use `London` not `UTC+0`.
+    * A local organization may go 20 years without needing an update. When there is a local or national change, it will be covered in the local news.
+      You may get by with infrequent/ad-hoc updates.
+    * Globally, in any given year, there will be several locales which do change their rules, and you may not be specifically aware of every change.
+      A global organization or service-provider should consider automatic updates.  For example, you might define a system-startup script or a
+      monthly cron-job to run `mysql_tzinfo_to_sql`.
 
 ### MySQL Permissions