--- a/docs/index.rst	Sat May 28 15:11:48 2016 +0200
+++ b/docs/index.rst	Mon May 23 19:14:48 2016 +0200
@@ -23,6 +23,7 @@
    installation_iis
    setup
    installation_puppet
+   upgrade
 
 **Usage**
 

--- a/docs/installation.rst	Sat May 28 15:11:48 2016 +0200
+++ b/docs/installation.rst	Mon May 23 19:14:48 2016 +0200
@@ -45,9 +45,6 @@
 
 You can now proceed to :ref:`setup`.
 
-To upgrade, simply update the repository with ``hg pull -u`` and restart the
-server.
-
 .. _installation-virtualenv:
 
 
@@ -123,90 +120,5 @@
 You can now proceed to :ref:`setup`.
 
 
-Upgrading Kallithea from Python Package Index (PyPI)
-----------------------------------------------------
-
-.. note::
-   It is strongly recommended that you **always** perform a database and
-   configuration backup before doing an upgrade.
-
-   These directions will use '{version}' to note that this is the version of
-   Kallithea that these files were used with.  If backing up your Kallithea
-   instance from version 0.1 to 0.2, the ``my.ini`` file could be
-   backed up to ``my.ini.0-1``.
-
-If using a SQLite database, stop the Kallithea process/daemon/service, and
-then make a copy of the database file::
-
- service kallithea stop
- cp kallithea.db kallithea.db.{version}
-
-Back up your configuration file::
-
- cp my.ini my.ini.{version}
-
-Ensure that you are using the Python virtual environment that you originally
-installed Kallithea in by running::
-
- pip freeze
-
-This will list all packages installed in the current environment.  If
-Kallithea isn't listed, activate the correct virtual environment::
-
- source /srv/kallithea/venv/bin/activate
-
-Once you have verified the environment you can upgrade Kallithea with::
-
- pip install --upgrade kallithea
-
-Then run the following command from the installation directory::
-
- paster make-config Kallithea my.ini
-
-This will display any changes made by the new version of Kallithea to your
-current configuration. It will try to perform an automerge. It is recommended
-that you recheck the content after the automerge.
-
-.. note::
-   Please always make sure your .ini files are up to date. Errors can
-   often be caused by missing parameters added in new versions.
-
-It is also recommended that you rebuild the whoosh index after upgrading since
-the new whoosh version could introduce some incompatible index changes. Please
-read the changelog to see if there were any changes to whoosh.
-
-The final step is to upgrade the database. To do this simply run::
-
- paster upgrade-db my.ini
-
-This will upgrade the schema and update some of the defaults in the database,
-and will always recheck the settings of the application, if there are no new
-options that need to be set.
-
-.. note::
-   The DB schema upgrade library has some limitations and can sometimes fail if you try to
-   upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,
-   upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X
-   You can always specify what version of Kallithea you want to install for example in pip
-   `pip install Kallithea==0.2`
-
-You may find it helpful to clear out your log file so that new errors are
-readily apparent::
-
- echo > kallithea.log
-
-Once that is complete, you may now start your upgraded Kallithea Instance::
-
- service kallithea start
-
-Or::
-
- paster serve /srv/kallithea/my.ini
-
-.. note::
-   If you're using Celery, make sure you restart all instances of it after
-   upgrade.
-
-
 .. _virtualenv: http://pypi.python.org/pypi/virtualenv
 .. _pylons: http://www.pylonsproject.org/

--- a/docs/installation_win.rst	Sat May 28 15:11:48 2016 +0200
+++ b/docs/installation_win.rst	Mon May 23 19:14:48 2016 +0200
@@ -1,8 +1,8 @@
 .. _installation_win:
 
-================================================================
-Installation and upgrade on Windows (7/Server 2008 R2 and newer)
-================================================================
+====================================================
+Installation on Windows (7/Server 2008 R2 and newer)
+====================================================
 
 
 First time install
@@ -178,8 +178,8 @@
   paster setup-db production.ini
 
 .. warning:: This time a *new* database will be installed. You must
-             follow a different step to later *upgrade* to a newer
-             Kallithea version)
+             follow a different process to later :ref:`upgrade <upgrade>`
+             to a newer Kallithea version.
 
 The script will ask you for confirmation about creating a new database, answer yes (y)
 
@@ -219,27 +219,3 @@
 - Using Apache. You can investigate here:
 
   - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4
-
-
-Upgrading
----------
-
-Stop running Kallithea
-Open a CommandPrompt like in Step 7 (cd to C:\Kallithea\Env\Scripts and activate) and type::
-
-  pip install kallithea --upgrade
-  cd \Kallithea\Bin
-
-Backup your production.ini file now.
-
-Then run::
-
-  paster make-config Kallithea production.ini
-
-Look for changes and update your production.ini accordingly.
-
-Next, update the database::
-
-  paster upgrade-db production.ini
-
-More details can be found in `<upgrade.html>`_.

--- a/docs/installation_win_old.rst	Sat May 28 15:11:48 2016 +0200
+++ b/docs/installation_win_old.rst	Mon May 23 19:14:48 2016 +0200
@@ -1,8 +1,8 @@
 .. _installation_win_old:
 
-======================================================================
-Installation and upgrade on Windows (XP/Vista/Server 2003/Server 2008)
-======================================================================
+==========================================================
+Installation on Windows (XP/Vista/Server 2003/Server 2008)
+==========================================================
 
 
 First-time install
@@ -217,8 +217,9 @@
 
  paster setup-db production.ini
 
-(this time a NEW database will be installed, you must follow a different
-step to later UPGRADE to a newer Kallithea version)
+.. warning:: This time a *new* database will be installed. You must
+             follow a different process to later :ref:`upgrade <upgrade>`
+             to a newer Kallithea version.
 
 The script will ask you for confirmation about creating a NEW database,
 answer yes (y)
@@ -260,23 +261,3 @@
 - Using Apache. You can investigate here:
 
   - https://groups.google.com/group/rhodecode/msg/c433074e813ffdc4
-
-
-Upgrading
----------
-
-Stop running Kallithea
-Open a CommandPrompt like in Step7 (VS2008 path + activate) and type::
-
- easy_install -U kallithea
- cd \Kallithea\Bin
-
-{ backup your production.ini file now} ::
-
- paster make-config Kallithea production.ini
-
-(check changes and update your production.ini accordingly) ::
-
- paster upgrade-db production.ini (update database)
-
-Full steps in http://packages.python.org/Kallithea/upgrade.html

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/docs/upgrade.rst	Mon May 23 19:14:48 2016 +0200
@@ -0,0 +1,140 @@
+.. _upgrade:
+
+===================
+Upgrading Kallithea
+===================
+
+This describes the process for upgrading Kallithea, independently of the
+Kallithea installation method.
+
+
+1. Stop the Kallithea web application
+-------------------------------------
+
+This step depends entirely on the web server software used to serve
+Kallithea, but in any case, Kallithea should not be running during
+the upgrade.
+
+.. note::
+    If you're using Celery, make sure you stop all instances during the
+    upgrade.
+
+
+2. Create a backup of both database and configuration
+-----------------------------------------------------
+
+You are of course strongly recommended to make backups regularly, but it
+is *especially* important to make a full database and configuration
+backup before performing a Kallithea upgrade.
+
+Back up your configuration
+^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Make a copy of your Kallithea configuration (``.ini``) file.
+
+If you are using :ref:`rcextensions <customization>`, you should also
+make a copy of the entire ``rcextensions`` directory.
+
+Back up your database
+^^^^^^^^^^^^^^^^^^^^^
+
+If using SQLite, simply make a copy of the Kallithea database (``.db``)
+file.
+
+If using PostgreSQL, please consult the documentation for the ``pg_dump``
+utility.
+
+If using MySQL, please consult the documentation for the ``mysqldump``
+utility.
+
+Look for ``sqlalchemy.db1.url`` in your configuration file to determine
+database type, settings, location, etc.
+
+
+3. Activate the Kallithea virtual environment (if any)
+------------------------------------------------------
+
+Verify that you are using the Python environment that you originally
+installed Kallithea in by running::
+
+    pip freeze
+
+This will list all packages installed in the current environment. If
+Kallithea isn't listed, activate the correct virtual environment.
+See the appropriate installation page for details.
+
+
+4. Install new version of Kallithea
+-----------------------------------
+
+Please refer to the instructions for the installation method you
+originally used to install Kallithea.
+
+If you originally installed using pip, it is as simple as::
+
+    pip install --upgrade kallithea
+
+If you originally installed from version control, it is as simple as::
+
+    cd my-kallithea-clone
+    hg pull -u
+    pip install -e .
+
+
+5. Upgrade your configuration
+-----------------------------
+
+Run the following command to upgrade your configuration (``.ini``) file::
+
+    paster make-config Kallithea my.ini
+
+This will display any changes made by the new version of Kallithea to your
+current configuration, and attempt an automatic merge. It is recommended
+that you check the contents after the merge.
+
+.. note::
+    Please always make sure your ``.ini`` files are up to date. Errors
+    can often be caused by missing parameters added in new versions.
+
+
+6. Upgrade your database
+------------------------
+
+To do this simply run::
+
+    paster upgrade-db my.ini
+
+This will upgrade the schema and update some of the defaults in the database,
+and will always recheck the settings of the application, if there are no new
+options that need to be set.
+
+.. note::
+    The DB schema upgrade library has some limitations and can sometimes fail if you try to
+    upgrade from older major releases. In such a case simply run upgrades sequentially, e.g.,
+    upgrading from 0.1.X to 0.3.X should be done like this: 0.1.X. > 0.2.X > 0.3.X.
+    You can always specify what version of Kallithea you want to install e.g. using pip:
+    ``pip install Kallithea==0.2``
+
+
+7. Rebuild the Whoosh full-text index
+-------------------------------------
+
+It is recommended that you rebuild the Whoosh index after upgrading since
+new Whoosh versions can introduce incompatible index changes.
+
+
+8. Start the Kallithea web application
+--------------------------------------
+
+This step once again depends entirely on the web server software used to
+serve Kallithea.
+
+Before starting the new version of Kallithea, you may find it helpful to
+clear out your log file so that new errors are readily apparent.
+
+.. note::
+    If you're using Celery, make sure you restart all instances of it after
+    upgrade.
+
+
+.. _virtualenv: http://pypi.python.org/pypi/virtualenv