Improve messaging and documentation around surplus schemata

Summary: Fixes T6795. Fixes T6813. We can give more tailored instructions for surplus schemata than we currently do, and provide more information on resolving them.

Test Plan:
  - Ran `storage adjust` with just surplus schemata (friendly warning).
  - Ran `storage adjust` with surplus schemata and other serious errors (more severe error).
  - Read document.

Reviewers: btrahan, chad

Reviewed By: chad

Subscribers: epriestley

Maniphest Tasks: T6795, T6813

Differential Revision: https://secure.phabricator.com/D11054

src/docs/user/configuration/storage_adjust.diviner

@@ -118,7 +118,7 @@ twice as much time performing schemata adjustments.
 Troubleshooting
 ===============
 
-When you apply adjustments, some adjustments may fail. The two most common
+When you apply adjustments, some adjustments may fail. Some of the most common
 errors you may encounter are:
 
   - **#1406 Data Too Long**: Usually this is caused by a very long object name
@@ -145,3 +145,47 @@ In general, adjustments are not critical. If you run into issues applying
 adjustments, it is safe to file a task in the upstream describing the problem
 you've encountered and continue using Phabricator normally until the issue can
 be resolved.
+
+Surplus Schemata
+================
+
+After performing adjustment, you may receive an error that a table or column is
+"Surplus". The error looks something like this:
+
+| Target | Error |
+| --- | --- |
+| phabricator_example.example_table | Surplus |
+
+Generally, "Surplus" means that Phabricator does not expect the table or column
+to exist. These surpluses usually exist because you (or someone else
+with database access) added the table or column manually. Rarely, they can
+also exist for other reasons. They are usually safe to delete, but because
+deleting them destroys data and Phabricator can not be sure that the table or
+column doesn't have anything important in it, it does not delete them
+automatically.
+
+If you recognize the schema causing the issue as something you added and you
+don't need it anymore, you can safely delete it. If you aren't sure whether
+you added it or not, you can move the data somewhere else and delete it later.
+
+To move a table, first create a database for it like `my_backups`. Then, rename
+the table to move it into that database (use the table name given in the error
+message):
+
+```lang=sql
+CREATE DATABASE my_backups;
+RENAME TABLE phabricator_example.example_table
+  TO my_backups.example_table;
+```
+
+Phabricator will ignore tables that aren't in databases it owns, so you can
+safely move anything you aren't sure about outside of the Phabricator databases.
+
+If you're sure you don't need a table, use `DROP TABLE` to destroy it,
+specifying the correct table name (the one given in the error message):
+
+```lang=sql
+DROP TABLE phabricator_example.example_table;
+```
+
+This will destroy the table permanently.

src/infrastructure/storage/management/workflow/PhabricatorStorageManagementWorkflow.php

@@ -595,6 +595,8 @@ abstract class PhabricatorStorageManagementWorkflow
       ->addColumn('target', array('title' => pht('Target')))
       ->addColumn('error', array('title' => pht('Error')));
 
+    $any_surplus = false;
+    $all_surplus = true;
     foreach ($errors as $error) {
       $pieces = array_select_keys(
         $error,
@@ -604,6 +606,12 @@ abstract class PhabricatorStorageManagementWorkflow
 
       $name = PhabricatorConfigStorageSchema::getIssueName($error['issue']);
 
+      if ($error['issue'] === PhabricatorConfigStorageSchema::ISSUE_SURPLUS) {
+        $any_surplus = true;
+      } else {
+        $all_surplus = false;
+      }
+
       $table->addRow(
         array(
           'target' => $target,
@@ -615,19 +623,50 @@ abstract class PhabricatorStorageManagementWorkflow
     $table->draw();
     $console->writeOut("\n");
 
-    $message = pht(
-      "The schemata have serious errors (detailed above) which the adjustment ".
-      "workflow can not fix.\n\n".
-      "If you are not developing Phabricator itself, report this issue to ".
-      "the upstream.\n\n".
-      "If you are developing Phabricator, these errors usually indicate that ".
-      "your schema specifications do not agree with the schemata your code ".
-      "actually builds.");
 
+    $message = array();
+    if ($all_surplus) {
+      $message[] = pht(
+        'You have surplus schemata (extra tables or columns which Phabricator '.
+        'does not expect). For information on resolving these '.
+        'issues, see the "Surplus Schemata" section in the "Managing Storage '.
+        'Adjustments" article in the documentation.');
+    } else {
+      $message[] = pht(
+        'The schemata have errors (detailed above) which the adjustment '.
+        'workflow can not fix.');
+
+      if ($any_surplus) {
+        $message[] = pht(
+          'Some of these errors are caused by surplus schemata (extra '.
+          'tables or columsn which Phabricator does not expect). These are '.
+          'not serious. For information on resolving these issues, see the '.
+          '"Surplus Schemata" section in the "Managing Storage Adjustments" '.
+          'article in the documentation.');
+      }
+
+      $message[] = pht(
+        'If you are not developing Phabricator itself, report this issue to '.
+        'the upstream.');
+
+      $message[] = pht(
+        'If you are developing Phabricator, these errors usually indicate '.
+        'that your schema specifications do not agree with the schemata your '.
+        'code actually builds.');
+    }
+    $message = implode("\n\n", $message);
+
+    if ($all_surplus) {
+      $console->writeOut(
+        "**<bg:yellow> %s </bg>**\n\n%s\n",
+        pht('SURPLUS SCHEMATA'),
+        phutil_console_wrap($message));
+    } else {
       $console->writeOut(
         "**<bg:red> %s </bg>**\n\n%s\n",
         pht('SCHEMATA ERRORS'),
         phutil_console_wrap($message));
+    }
 
     return 2;
   }