From 85cc13b607237d1e999bbefa201ab45092e7e492 Mon Sep 17 00:00:00 2001
From: tuomaspelkonen <tuomas.pelkonen@fb.com>
Date: Mon, 11 Apr 2011 16:47:51 -0700
Subject: [PATCH] Added documentation for schema upgrade.

Summary:
Documentation describes how to use the script to upgrade schema.

Test Plan:
Generated the documentation and it looked good.

Reviewed By: epriestley
Reviewers: epriestley
CC: jungejason, epriestley
Differential Revision: 124
---
 src/docs/configuration_guide.diviner | 13 +++++------
 src/docs/upgrade_schema.diviner      | 32 ++++++++++++++++++++++++++++
 2 files changed, 39 insertions(+), 6 deletions(-)
 create mode 100644 src/docs/upgrade_schema.diviner

diff --git a/src/docs/configuration_guide.diviner b/src/docs/configuration_guide.diviner
index f00bc2db33..8597425ab9 100644
--- a/src/docs/configuration_guide.diviner
+++ b/src/docs/configuration_guide.diviner
@@ -16,12 +16,8 @@ schemata into it. First, load the initial database schema.
 
   mysql -uroot < path/to/phabricator/resources/sql/init/initialize.sql
 
-Next, load each of the database patches in order. (One day this will be
-better.)
-
-  mysql -uroot < path/to/phabricator/resources/sql/patches/000.project.sql
-  mysql -uroot < path/to/phabricator/resources/sql/patches/001...
-  ...
+After this you need to upgrade the schema see @{article:Upgrading Schema},
+but you need to finish the rest of the configuration first.
 
 = Configuring Apache =
 
@@ -119,3 +115,8 @@ configuring Apache:
 
 Now, look through ##default.conf.php## and override any options you want to
 change by providing overrides in ##myconfig.conf.php##.
+
+= Upgrading Schema =
+
+After you have configured Phabricator, you need to upgrade the database
+schema, see @{article:Upgrading Schema}
diff --git a/src/docs/upgrade_schema.diviner b/src/docs/upgrade_schema.diviner
new file mode 100644
index 0000000000..7c3c2c940d
--- /dev/null
+++ b/src/docs/upgrade_schema.diviner
@@ -0,0 +1,32 @@
+@title Upgrading Schema
+@group config
+
+This document descibes how to upgrade the database schema.
+
+= Prerequisites =
+
+This document assumes you've already initialized the MySQL database and
+configured your Phabricator environment. If you haven't, see
+@{article:Configuration Guide}.
+
+= Loading patches =
+
+If you are doing this for the first time to a freshly installed MySQL database,
+run the following command:
+
+  PHABRICATOR_ENV=<your_config> php path/to/phabricator/scripts/sql/upgrade_schema.php 0
+
+This will install all the patches starting from 0. Running this script will
+store the information of the latest installed patch in the Phabricator database.
+Next time you want to upgrade your schema, just run:
+
+  PHABRICATOR_ENV=<your_config> php path/to/phabricator/scripts/sql/upgrade_schema.php
+
+This will install all the patches that are new since the last time you ran
+this script.
+
+If you need to upgrade the schema starting from a specific patch, just run:
+
+  PHABRICATOR_ENV=<your_config> php path/to/phabricator/scripts/sql/upgrade_schema.php <patch_number>
+
+However, this isn't usually needed.