Bug 1067416 - reorganize and update Bugzilla docs.

1 files changed, 69 insertions, 0 deletions

diff --git a/docs/en/rst/installing/upgrading-with-git.rst b/docs/en/rst/installing/upgrading-with-git.rst
new file mode 100644
index 000000000..78b4fb1e0
--- /dev/null
+++ b/docs/en/rst/installing/upgrading-with-git.rst
@@ -0,0 +1,69 @@
+.. _upgrading-with-git:
+
+Upgrading with Git
+##################
+
+Upgrading to new Bugzilla releases is very simple, and you can upgrade
+from any version to any later version in one go - there is no need for
+intermediate steps. There is a script named :file:`checksetup.pl` included
+with Bugzilla that will automatically do all of the database migration
+for you.
+
+.. include:: upgrading-with-1.inc.rst
+
+You can see if you have local code customizations using:
+
+:command:`git diff`
+
+If that comes up empty, then run:
+
+:command:`git log | head`
+
+and see if the last commit looks like one made by the Bugzilla team, or
+by you. If it looks like it was made by us, then you have made no local
+code customizations.
+
+.. _start-upgrade-git:
+
+Starting the Upgrade
+====================
+
+When you are ready to go:
+
+#. Shut down your Bugzilla installation by putting some explanatory text
+   in the :param:`shutdownhtml` parameter.
+
+#. Make all necessary :ref:`backups <backups>`.
+   *THIS IS VERY IMPORTANT*. If anything goes wrong during the upgrade,
+   having a backup allows you to roll back to a known good state.
+
+.. _upgrade-files-git:
+
+Getting The New Bugzilla
+========================
+
+In the commands below, ``$BUGZILLA_HOME`` represents the directory
+in which Bugzilla is installed. Assuming you followed the installation
+instructions and your Bugzilla is a checkout of a stable branch,
+you can get the latest point release of your current version by simply doing:
+
+:command:`cd $BUGZILLA_HOME`
+
+:command:`git pull`
+
+If you want to upgrade to a newer release of Bugzilla, then you will
+additionally need to do:
+
+:command:`git checkout bugzilla-X.X-stable`
+
+where "X.X" is the 2-digit version number of the stable version you want to
+upgrade to (e.g. "4.4").
+
+.. note:: Do not attempt to downgrade Bugzilla this way - it won't work.
+
+If you have local code customizations, git will attempt to merge them. If
+it fails, then you should implement the plan you came up with when you
+detected these customizations in the step above, before you started the
+upgrade.
+
+.. include:: upgrading-with-2.inc.rst