totten
--- a/docs/upgrade/drupal8.md 0 → 100644
+++ b/docs/upgrade/drupal8.md 0 → 100644
+## Upgrade the database
+
+Choose one of the following methods:
+
+* Run the following `cv` command from within your site:
+
+    ```bash
+    cv upgrade:db
+    ```
+
+    !!! tip "Tip: Preview upgrade steps"
+
+        The `cv upgrade:db` command accepts a `--dry-run` option to show what changes will be executed.
+        For the maximum detail, use `cv upgrade:db --dry-run -vv`.
+
+* Or, run the following `drush` command from within your site:
--- a/docs/upgrade/drupal8.md 0 → 100644
+++ b/docs/upgrade/drupal8.md 0 → 100644
+
+Choose one of the following methods:
+
+* Run the command `composer update`. This finds the newest version which *matches the current constraint*.  For example, if the
+  constraint specifies `~5.29.0`, then `composer update` will find `5.29.2` or `5.29.3` or similar.
+
+    ```bash
+    composer update civicrm/civicrm-{core,packages,drupal-8}
+    ```
+
+* Run the command `composer require`. This *changes the current constraint*. For example, to switch to `~5.31.0`, run:
+
+    ```bash
+    composer require civicrm/civicrm-{core,packages,drupal-8}:~5.31.0
+    ```
+