Provide more detailed guidance on upgrading Phabricator and the "stable" branch

Summary: Maintaining "stable" is worthwhile now that we're running the cluster, so document its existence.

Test Plan: Reading.

Reviewers: btrahan

Reviewed By: btrahan

Subscribers: epriestley

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

src/docs/user/installation_guide.diviner

@@ -167,23 +167,10 @@ If it doesn't show up, add:
 
 ..to "/etc/php.d/apc.ini" or the "php.ini" file indicated by "php -i".
 
-= Updating Phabricator =
-
-Since Phabricator is under active development, you should update frequently. To
-update Phabricator:
-
-  - Stop the webserver (including `php-fpm`, if you use it).
-  - Run `git pull` in `libphutil/`, `arcanist/` and `phabricator/`.
-  - Run `phabricator/bin/storage upgrade`.
-  - Restart the webserver (and `php-fpm`, if you stopped it earlier).
-
-For more details, see @{article:Configuration Guide}. You can use a script
-similar to this one to automate the process:
-
-http://www.phabricator.com/rsrc/install/update_phabricator.sh
-
 = Next Steps =
 
 Continue by:
 
-  - configuring Phabricator with the @{article:Configuration Guide}.
+  - configuring Phabricator with the @{article:Configuration Guide}; or
+  - learning how to keep Phabricator up to date with
+    @{article:Upgrading Phabricator}.

src/docs/user/upgrading.diviner

@@ -0,0 +1,130 @@
+@title Upgrading Phabricator
+@group intro
+
+This document contains instructions for keeping Phabricator up to date.
+
+Overview
+========
+
+Phabricator is under active development, and new features are released
+continuously. Staying up to date will keep your install secure.
+
+We recommend installs upgrade regularly (every 1-2 weeks). Upgrades usually go
+smoothly and complete in a few minutes. If you put off upgrades for a long
+time, it may take a lot more work to bring things up to date if you want access
+to a useful new feature or an important security change.
+
+
+Staying On Top of Changes
+=========================
+
+We release a weekly [[https://secure.phabricator.com/w/changelog | Changelog]],
+which describes changes in the previous week. You can look at the changelogs
+for an idea of what new features are available, upcoming changes, security
+information, and warnings about compatibility issues or migrations.
+
+
+Stable Branch
+=============
+
+You can either run the `master` or `stable` branch of Phabricator. The `stable`
+branch is run in the [[ https://phacility.com | Phacility Cluster ]], and lags
+about a week behind `master`.
+
+The `stable` branch is a little more stable than `master`, and may be helpful
+if you administrate a larger install.
+
+We promote `master` to `stable` about once a week, then publish the changelog
+and deploy the cluster. During the week, major bugfixes are cherry-picked to
+the `stable` branch. The changelog lists the `stable` hashes for that week,
+as well as any fixes which were cherry-picked.
+
+To switch to `stable`, check the branch out in each working copy:
+
+  phabricator/ $ git checkout stable
+  arcanist/ $ git checkout stable
+  libphutil/ $ git checkout stable
+
+You can now follow the upgrade process normally.
+
+
+Upgrade Process
+===============
+
+IMPORTANT: You **MUST** restart Apache or PHP-FPM after upgrading.
+
+Phabricator runs on many different systems, with many different webservers.
+Given this diversity, we don't currently maintain a comprehensive upgrade
+script which can work on any system. However, the general steps are the same
+on every system:
+
+  - Stop the webserver (including `php-fpm`, if you use it).
+  - Stop the daemons, with `phabricator/bin/phd stop`.
+  - Run `git pull` in `libphutil/`, `arcanist/` and `phabricator/`.
+  - Run `phabricator/bin/storage upgrade`.
+  - Start the daemons, with `phabricator/bin/phd start`.
+  - Restart the webserver (and `php-fpm`, if you stopped it earlier).
+
+For some more discussion details, see @{article:Configuration Guide}.
+
+This template script roughly outlines the steps required to upgrade Phabricator.
+You'll need to adjust paths and commands a bit for your particular system:
+
+```lang=sh
+#!/bin/sh
+
+set -e
+set -x
+
+# This is an example script for updating Phabricator, similar to the one used to
+# update <https://secure.phabricator.com/>. It might not work perfectly on your
+# system, but hopefully it should be easy to adapt. This script is not intended
+# to work without modifications.
+
+# NOTE: This script assumes you are running it from a directory which contains
+# arcanist/, libphutil/, and phabricator/.
+
+ROOT=`pwd` # You can hard-code the path here instead.
+
+### UPDATE WORKING COPIES ######################################################
+
+cd $ROOT/libphutil
+git pull
+
+cd $ROOT/arcanist
+git pull
+
+cd $ROOT/phabricator
+git pull
+
+
+### CYCLE WEB SERVER AND DAEMONS ###############################################
+
+# Stop daemons.
+$ROOT/phabricator/bin/phd stop
+
+# If running the notification server, stop it.
+# $ROOT/phabricator/bin/aphlict stop
+
+# Stop the webserver (apache, nginx, lighttpd, etc). This command will differ
+# depending on which system and webserver you are running: replace it with an
+# appropriate command for your system.
+# NOTE: If you're running php-fpm, you should stop it here too.
+
+sudo /etc/init.d/httpd stop
+
+
+# Upgrade the database schema. You may want to add the "--force" flag to allow
+# this script to run noninteractively.
+$ROOT/phabricator/bin/storage upgrade
+
+# Restart the webserver. As above, this depends on your system and webserver.
+# NOTE: If you're running php-fpm, restart it here too.
+sudo /etc/init.d/httpd start
+
+# Restart daemons.
+$ROOT/phabricator/bin/phd start
+
+# If running the notification server, start it.
+# $ROOT/phabricator/bin/aphlict start
+```