WIP

diff --git a/docs/en/rst/about.rst b/docs/en/rst/about/index.rst
similarity index 100%
rename from docs/en/rst/about.rst
rename to docs/en/rst/about/index.rst

diff --git a/docs/en/rst/administering.rst b/docs/en/rst/administering.rst
deleted file mode 100644 (file)
index f772060..0000000
--- a/docs/en/rst/administering.rst
+++ /dev/null
@@ -1,26 +0,0 @@
-.. _administering:
-
-======================
-Administering Bugzilla
-======================
-
-For those with :group:`admin` privileges, Bugzilla can be administered using
-the :guilabel:`Administration` link in the header. The administrative
-controls are divided into several sections:
-
-.. toctree::
-   :maxdepth: 2
-
-   administering/parameters
-   administering/preferences
-   administering/users
-   administering/categorization
-   administering/flags
-   administering/custom-fields
-   administering/field-values
-   administering/workflow
-   administering/groups
-   administering/keywords
-   administering/whining
-   administering/quips
-   administering/extensions

diff --git a/docs/en/rst/administering/index.rst b/docs/en/rst/administering/index.rst
new file mode 100644 (file)
index 0000000..5f8b3cc
--- /dev/null
+++ b/docs/en/rst/administering/index.rst
@@ -0,0 +1,26 @@
+.. _administering:
+
+======================
+Administering Bugzilla
+======================
+
+For those with :group:`admin` privileges, Bugzilla can be administered using
+the :guilabel:`Administration` link in the header. The administrative
+controls are divided into several sections:
+
+.. toctree::
+   :maxdepth: 2
+
+   parameters
+   preferences
+   users
+   categorization
+   flags
+   custom-fields
+   field-values
+   workflow
+   groups
+   keywords
+   whining
+   quips
+   extensions

diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py
index 6a0349b95eb91584a6c58a3765b5c72ab76e6076..2f0c722ffdc3d852ea421fdc53e5d672019ccf8b 100644 (file)
--- a/docs/en/rst/conf.py
+++ b/docs/en/rst/conf.py
@@ -78,7 +78,7 @@ for line in open("../../../Bugzilla/Constants.pm"):
 
 # List of patterns, relative to source directory, that match files and
 # directories to ignore when looking for source files.
-exclude_patterns = []
+exclude_patterns = ['*.inc.rst']
 
 # The reST default role (used for this markup: `text`) to use for all documents.
 #default_role = None

diff --git a/docs/en/rst/customizing.rst b/docs/en/rst/customizing.rst
deleted file mode 100644 (file)
index 9f7887c..0000000
--- a/docs/en/rst/customizing.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. highlight:: perl
-
-.. _customizing:
-
-====================
-Customizing Bugzilla
-====================
-
-.. toctree::
-   :maxdepth: 2
-
-   customizing/existing-parameters
-   customizing/extensions
-   customizing/skins
-   customizing/languages
-   customizing/templates
-   customizing/who-can-change-what
-   customizing/writing-extensions

diff --git a/docs/en/rst/customizing/index.rst b/docs/en/rst/customizing/index.rst
new file mode 100644 (file)
index 0000000..71b08b5
--- /dev/null
+++ b/docs/en/rst/customizing/index.rst
@@ -0,0 +1,18 @@
+.. highlight:: perl
+
+.. _customizing:
+
+====================
+Customizing Bugzilla
+====================
+
+.. toctree::
+   :maxdepth: 2
+
+   existing-parameters
+   extensions
+   skins
+   languages
+   templates
+   who-can-change-what
+   writing-extensions

diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst
index 07506bf87ed35492168ebdf47e2fceb28e03bfe8..386cefc4ef7049b858e2c28350f0703e29519d17 100644 (file)
--- a/docs/en/rst/index.rst
+++ b/docs/en/rst/index.rst
@@ -6,11 +6,11 @@ Bugzilla Documentation
    :maxdepth: 2
    :numbered:
 
-   about
-   installing
-   upgrading
-   maintaining
-   customizing
-   integrating
-   administering
-   using
+   about/index
+   installing/index
+   upgrading/index
+   maintaining/index
+   customizing/index
+   integrating/index
+   administering/index
+   using/index

diff --git a/docs/en/rst/installing.rst b/docs/en/rst/installing/index.rst
similarity index 82%
rename from docs/en/rst/installing.rst
rename to docs/en/rst/installing/index.rst
index 97e56d9ef2bec2d06fdfb048b2beac96dcab332b..608185b70f20fdf3b03010612e3af9bace69dbaa 100644 (file)
--- a/docs/en/rst/installing.rst
+++ b/docs/en/rst/installing/index.rst
@@ -21,10 +21,10 @@ case, you may want to read the :ref:`Quick Start instructions <quick-start>`.
 .. toctree::
    :maxdepth: 2
 
-   installing/quick-start
-   installing/linux
-   installing/windows
-   installing/mac-os-x
-   installing/post-install-config
-   installing/migrating
-   installing/moving
+   quick-start
+   linux
+   windows
+   mac-os-x
+   post-install-config
+   migrating
+   moving

diff --git a/docs/en/rst/integrating.rst b/docs/en/rst/integrating/index.rst
similarity index 76%
rename from docs/en/rst/integrating.rst
rename to docs/en/rst/integrating/index.rst
index 6c4cb2e72b7d7bbf8d66e4ba58fcf806bad5f118..ad1f412c9ee3f029a8389b1158bafd930239a5a7 100644 (file)
--- a/docs/en/rst/integrating.rst
+++ b/docs/en/rst/integrating/index.rst
@@ -7,6 +7,6 @@ Integrating with Bugzilla
 .. toctree::
    :maxdepth: 2
 
-   integrating/apis
-   integrating/tips
+   apis
+   tips
    

diff --git a/docs/en/rst/maintaining/backups.rst b/docs/en/rst/maintaining/backups.rst
index bef3c3ada46130fe1d7748a477762b9237d8114f..384c79437b06ad092e5e53152d6807e7613da315 100644 (file)
--- a/docs/en/rst/maintaining/backups.rst
+++ b/docs/en/rst/maintaining/backups.rst
@@ -31,9 +31,8 @@ PostgreSQL
 Bugzilla
 ========
 
-It's also a good idea to back up the Bugzilla directory itself, as there are
-some data files and configuration files stored there which you would want to
-retain. A simple recursive copy will do the job here.
+The Bugzilla directory contains some data files and configuration files which
+you would want to retain. A simple recursive copy will do the job here.
 
 :command:`cp -rp $BUGZILLA_HOME /var/backups/bugzilla`
 

diff --git a/docs/en/rst/maintaining.rst b/docs/en/rst/maintaining/index.rst
similarity index 51%
rename from docs/en/rst/maintaining.rst
rename to docs/en/rst/maintaining/index.rst
index 299f011be88e17b48067d3818cb705633fef51cb..e92c8c555253f9a8d6a6caf4e0f48e3f353cfa01 100644 (file)
--- a/docs/en/rst/maintaining.rst
+++ b/docs/en/rst/maintaining/index.rst
@@ -7,7 +7,7 @@ Maintaining Bugzilla
 .. toctree::
    :maxdepth: 2
 
-   maintaining/upgrades
-   maintaining/backups
-   maintaining/sanity-check
-   maintaining/merging-accounts
+   upgrades
+   backups
+   sanity-check
+   merging-accounts

diff --git a/docs/en/rst/maintaining/upgrades.rst b/docs/en/rst/maintaining/upgrades.rst
index e02a536f310cc003121f20e70551294537a4fa92..99af808f7dc0ced22bd47056981ede6c66dcbdfb 100644 (file)
--- a/docs/en/rst/maintaining/upgrades.rst
+++ b/docs/en/rst/maintaining/upgrades.rst
@@ -6,8 +6,9 @@ Upgrades
 For details on how to upgrade Bugzilla, see the :ref:`upgrading` chapter.
 
 Bugzilla can automatically notify administrators when new releases are
-available if the  :guilabel:`upgrade_notification` parameter is set. Administrators
-will see these notifications when they access the Bugzilla home page. Bugzilla
-will check once per day for new releases. If you are behind a proxy, you may
-have to set the :guilabel:`proxy_url` parameter accordingly. If the proxy
-requires authentication, use the ``http://user:pass@proxy_url/`` syntax.
+available if the :param:`upgrade_notification` parameter is set.
+Administrators will see these notifications when they access the Bugzilla home
+page. Bugzilla will check once per day for new releases. If you are behind a
+proxy, you may have to set the :param:`proxy_url` parameter accordingly. If
+the proxy requires authentication, use the
+:paramval:`http://user:pass@proxy_url/` syntax.

diff --git a/docs/en/rst/upgrading.rst b/docs/en/rst/upgrading.rst
deleted file mode 100644 (file)
index b2a32d1..0000000
--- a/docs/en/rst/upgrading.rst
+++ /dev/null
@@ -1,14 +0,0 @@
-.. _upgrading:
-
-==================
-Upgrading Bugzilla
-==================
-
-.. toctree::
-   :maxdepth: 2
-
-   upgrading/overview
-   upgrading/upgrading-with-git
-   upgrading/upgrading-from-bazaar
-   upgrading/upgrading-from-cvs
-   upgrading/upgrading-with-a-tarball

diff --git a/docs/en/rst/upgrading/index.rst b/docs/en/rst/upgrading/index.rst
new file mode 100644 (file)
index 0000000..937fdae
--- /dev/null
+++ b/docs/en/rst/upgrading/index.rst
@@ -0,0 +1,15 @@
+.. _upgrading:
+
+==================
+Upgrading Bugzilla
+==================
+
+.. toctree::
+   :maxdepth: 2
+
+   overview
+   upgrading-with-git
+   migrating-from-bzr
+   migrating-from-cvs
+   migrating-from-a-tarball
+   upgrading-with-a-tarball

diff --git a/docs/en/rst/upgrading/upgrading-from-1.rst.inc b/docs/en/rst/upgrading/migrating-from-1.rst.inc
similarity index 64%
rename from docs/en/rst/upgrading/upgrading-from-1.rst.inc
rename to docs/en/rst/upgrading/migrating-from-1.rst.inc
index a53d050d74b06fd2befd40fac3bbbb2961972d45..481d1b2afcea87e9d4e7133e6729ec06262f764e 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-1.rst.inc
+++ b/docs/en/rst/upgrading/migrating-from-1.rst.inc
@@ -1,7 +1,7 @@
 .. This file is included in multiple places, so can't have labels as they
    appear as duplicates.
    
-The procedure to switch to Git is as follows. The idea is to switch version
+The procedure to migrate to Git is as follows. The idea is to switch version
 control systems without changing the version of Bugzilla you are using,
 to minimise the risk of conflict or problems. Any major upgrade can then
 happen as a separate step. 
@@ -10,14 +10,16 @@ Update Bugzilla To The Latest Point Release
 ===========================================
 
 It is recommended that you switch to Git while using the latest
-point release for your major version, so if you aren't running that, you may
+point release for your version, so if you aren't running that, you may
 want to do a minor upgrade first.
 
 .. todo:: Is this actually necessary? It adds several extra steps. What are we
           trying to avoid here? If we do have to do it, can we avoid them
           having to work out the latest point release manually? And do the
           bzr and CVS update commands take the full version number including
-          the third digit, or do they just take major and minor?
+          the third digit, or do they just take major and minor? We need to
+          make sure all commands operate on the same version number style,
+          and that it's clearly explained.
 
 First, you need to find what version of Bugzilla you are using. It should be
 in the top right corner of the front page but, if not, open the file
@@ -52,26 +54,3 @@ Then run checksetup to upgrade your database:
 
 You should then test your Bugzilla carefully, or just use it for a day or two,
 to make sure it's all still working fine.
-
-Download Code from Git
-======================
-
-Download a copy of your current version of Bugzilla from the git repository
-into a separate directory alongside your existing Bugzilla installation
-(which we will assume is in a directory called :file:`bugzilla`).
-
-You will need a copy of the git program. All Linux distributions have it;
-search your package manager for "git". On Windows or Mac OS X, you can
-`download the official build <http://www.git-scm.com/downloads>`_.
-
-Once git is installed, run these commands to pull a copy of Bugzilla:
-
-:command:`git clone https://git.mozilla.org/bugzilla/bugzilla bugzilla-new`
-
-:command:`cd bugzilla-new`
-
-:command:`git checkout $VERSION`
-
-Replace $VERSION with the two-digit version number of your current Bugzilla, e.g.
-4.2. These command will automatically change your version to the latest
-point release of version $VERSION.

diff --git a/docs/en/rst/upgrading/upgrading-from-2.rst.inc b/docs/en/rst/upgrading/migrating-from-2.rst.inc
similarity index 82%
rename from docs/en/rst/upgrading/upgrading-from-2.rst.inc
rename to docs/en/rst/upgrading/migrating-from-2.rst.inc
index 5d413ed7775fd03034758571cfc0bbc63222cab9..e49ca34ed2bbd83ea3d4f1fbe743ba8304b385a2 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-2.rst.inc
+++ b/docs/en/rst/upgrading/migrating-from-2.rst.inc
@@ -1,6 +1,29 @@
 .. This file is included in multiple places, so can't have labels as they
    appear as duplicates.
-   
+
+Download Code from Git
+======================
+
+Download an additional copy of your *current* version of Bugzilla from the git
+repository into a separate directory alongside your existing Bugzilla
+installation (which we will assume is in a directory called :file:`bugzilla`).
+
+You will need a copy of the git program. All Linux distributions have it;
+search your package manager for "git". On Windows or Mac OS X, you can
+`download the official build <http://www.git-scm.com/downloads>`_.
+
+Once git is installed, run these commands to pull a copy of Bugzilla:
+
+:command:`git clone https://git.mozilla.org/bugzilla/bugzilla bugzilla-new`
+
+:command:`cd bugzilla-new`
+
+:command:`git checkout $VERSION`
+
+Replace $VERSION with the two-digit version number of your current Bugzilla, e.g.
+4.2. These command will automatically switch your checkout to be a copy of
+the latest point release of version $VERSION.
+
 Save Any Local Customizations
 =============================
 

diff --git a/docs/en/rst/upgrading/migrating-from-a-tarball.rst b/docs/en/rst/upgrading/migrating-from-a-tarball.rst
new file mode 100644 (file)
index 0000000..b84eacf
--- /dev/null
+++ b/docs/en/rst/upgrading/migrating-from-a-tarball.rst
@@ -0,0 +1,25 @@
+.. _migrating-from-a-tarball:
+
+Migrating from a Tarball
+########################
+
+.. todo:: Need to check the diff command in the tarball case using a real
+          tarball and git checkout
+
+.. |diffcommand|   replace:: :command:`diff -ru -x data -x .git ../bugzilla-new . > patch.diff`
+.. |extstatusinfo| replace:: Copy across any subdirectories which do not exist
+                             in your new install.
+
+The procedure to migrate to Git is as follows. The idea is to switch without
+changing the version of Bugzilla you are using, to minimise the risk of
+conflict or problems. Any major upgrade can then happen as a separate step. 
+
+Find Your Current Bugzilla Version
+==================================
+
+First, you need to find what version of Bugzilla you are using. It should be
+in the top right corner of the front page but, if not, open the file
+:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for
+:code:`BUGZILLA_VERSION`.
+
+.. include:: migrating-from-2.rst.inc

diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/migrating-from-bzr.rst
similarity index 69%
rename from docs/en/rst/upgrading/upgrading-from-bazaar.rst
rename to docs/en/rst/upgrading/migrating-from-bzr.rst
index c368db53c308bd8e047ae6ba54bed87c11623b7a..ce693ad9050d18583a82e0d12cfa417c4f6c8650 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-bazaar.rst
+++ b/docs/en/rst/upgrading/migrating-from-bzr.rst
@@ -1,11 +1,11 @@
-.. _upgrading-from-bazaar:
+.. _migrating-from-bazaar:
 
-Upgrading from Bazaar
+Migrating from Bazaar
 #####################
 
 .. |updatecommand| replace:: :command:`bzr up -r tag:bugzilla-$VERSION`
 .. |diffcommand|   replace:: :command:`bzr diff > patch.diff`
 .. |extstatusinfo| replace:: The command :command:`bzr status extensions/` should help you work out what you added, if anything.
 
-.. include:: upgrading-from-1.rst.inc
-.. include:: upgrading-from-2.rst.inc
+.. include:: migrating-from-1.rst.inc
+.. include:: migrating-from-2.rst.inc

diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/migrating-from-cvs.rst
similarity index 71%
rename from docs/en/rst/upgrading/upgrading-from-cvs.rst
rename to docs/en/rst/upgrading/migrating-from-cvs.rst
index 03456966a67266244349b51e8ab09a3e2cf9fbc2..023b39856adbeb3d430acd5e1711c906560e110c 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-from-cvs.rst
+++ b/docs/en/rst/upgrading/migrating-from-cvs.rst
@@ -1,13 +1,13 @@
-.. _upgrading-from-cvs:
+.. _migrating-from-cvs:
 
-Upgrading from CVS
+Migrating from CVS
 ##################
 
 .. |updatecommand| replace:: :command:`cvs update -rBUGZILLA-$VERSION-STABLE -dP`
 .. |diffcommand|   replace:: :command:`cvs diff -puN > patch.diff`
 .. |extstatusinfo| replace:: The command :command:`cvs status extensions/` should help you work out what you added, if anything.
 
-.. include:: upgrading-from-1.rst.inc
-.. include:: upgrading-from-2.rst.inc
+.. include:: migrating-from-1.rst.inc
+.. include:: migrating-from-2.rst.inc
 
 

diff --git a/docs/en/rst/upgrading/overview.rst b/docs/en/rst/upgrading/overview.rst
index cab23521be4eec98b584c6816158ac8060a36f04..e779caf5222f8829b9e1a21f4292cdbe90eae18f 100644 (file)
--- a/docs/en/rst/upgrading/overview.rst
+++ b/docs/en/rst/upgrading/overview.rst
@@ -14,10 +14,10 @@ the method by which you obtain the code along the way.
    to test the upgrade on a development server first, using a copy of the
    production data and configuration.
  
-Bugzilla uses the Git version control system to store its code. A modern Bugzilla
-installation consists of a checkout of a stable version of the code from our
-Git repository. This makes upgrading much easier. If this is
-true of your installation, see :ref:`upgrading-with-git`.
+Bugzilla uses the Git version control system to store its code. A modern
+Bugzilla installation consists of a checkout of a stable version of the code
+from our Git repository. This makes upgrading much easier. If this is
+already true of your installation, see :ref:`upgrading-with-git`.
 
 Before Git, we used to use Bazaar and, before that, CVS. If your installation
 of Bugzilla consists of a checkout from one of those two systems, you need to
@@ -27,7 +27,7 @@ upgrade in three steps:
 2. move to Git while staying on exactly the same release;
 3. upgrade to the latest Bugzilla using the instructions for :ref:`upgrading-with-git`.
 
-See :ref:`upgrading-from-bazaar` or :ref:`upgrading-from-cvs` as appropriate.
+See :ref:`migrating-from-bazaar` or :ref:`migrating-from-cvs` as appropriate.
 
 Some Bugzillas were installed simply by downloading a copy of the code as
 an archive file ("tarball"). However, recent tarballs have included source
@@ -39,9 +39,10 @@ version control system your copy of Bugzilla recognizes, look for the
 following subdirectories in your root Bugzilla directory:
 
 * :file:`.git`: you installed using Git - follow :ref:`upgrading-with-git`
-* :file:`.bzr`: you installed using Bazaar - follow :ref:`upgrading-from-bazaar`
-* :file:`CVS`: you installed using CVS - follow :ref:`upgrading-from-cvs`
-* none of the above: you installed using an old tarball - follow :ref:`upgrading-with-a-tarball`
+* :file:`.bzr`: you installed using Bazaar - follow :ref:`migrating-from-bazaar`
+* :file:`CVS`: you installed using CVS - follow :ref:`migrating-from-cvs`
+* none of the above: you installed using an old tarball - follow
+  :ref:`migrating-from-a-tarball`
 
 It is also possible, particularly if your server machine does not have and
 cannot be configured to have access to the public internet, to upgrade using

diff --git a/docs/en/rst/upgrading/upgrading-with-1.rst.inc b/docs/en/rst/upgrading/upgrading-with-1.rst.inc
new file mode 100644 (file)
index 0000000..4861f6e
--- /dev/null
+++ b/docs/en/rst/upgrading/upgrading-with-1.rst.inc
@@ -0,0 +1,41 @@
+Before You Upgrade
+==================
+
+Before you start your upgrade, there are a few important
+steps to take:
+
+#. Read the
+   `Release Notes <http://www.bugzilla.org/releases/>`_ of the version you're
+   upgrading to and all intermediate versions, particularly the "Notes for
+   Upgraders" sections, if present. They may make you aware of additional
+   considerations.
+
+#. Run the :ref:`sanity-check` on your installation. Attempt to fix all
+   warnings that the page produces before you start, or it's
+   possible that you may experience problems during your upgrade.
+
+#. Work out how to :ref:`back up <backups>` your Bugzilla entirely, and
+   how to restore from a backup if need be.
+
+Customized Bugzilla?
+--------------------
+
+If you have modified the code or templates of your Bugzilla,
+then upgrading requires a bit more thought and effort than the simple process
+below. See :ref:`template-method` for a discussion of the various methods of
+code customization that may have been used.
+
+The larger the jump you are trying to make, the more difficult it
+is going to be to upgrade if you have made local code customizations.
+Upgrading from 4.2 to 4.2.1 should be fairly painless even if
+you are heavily customized, but going from 2.18 to 4.2 is going
+to mean a fair bit of work re-writing your local changes to use
+the new files, logic, templates, etc. If you have done no local
+changes at all, however, then upgrading should be approximately
+the same amount of work regardless of how long it has been since
+your version was released.
+
+If you have made customizations, you should do the upgrade on a test system
+with the same configuration and make sure all your customizations still work.
+If not, port and test them so you have them ready to reapply once you do
+the upgrade for real.

diff --git a/docs/en/rst/upgrading/upgrading-with-2.rst.inc b/docs/en/rst/upgrading/upgrading-with-2.rst.inc
new file mode 100644 (file)
index 0000000..d8e2dbf
--- /dev/null
+++ b/docs/en/rst/upgrading/upgrading-with-2.rst.inc
@@ -0,0 +1,32 @@
+Upgrading the Database
+======================
+
+Run :file:`checksetup.pl`. This will do everything required to convert
+your existing database and settings to the new version.
+
+:command:`cd $BUGZILLA_HOME`
+
+:command:`./checksetup.pl`
+
+   .. warning:: For some upgrades, running :file:`checksetup.pl` on a large
+      installation (75,000 or more bugs) can take a long time,
+      possibly several hours, if e.g. indexes need to be rebuilt. If this
+      length of downtime would be a problem for you, you can determine
+      timings for your particular situation by doing a test upgrade on a
+      development server with the production data.
+
+:file:`checksetup.pl` may also tell you that you need some additional
+Perl modules, or newer versions of the ones you have. You will need to
+install these, either system-wide or using the :file:`install-module.pl`
+script that :file:`checksetup.pl` recommends.
+
+Finishing The Upgrade
+=====================
+
+#. Reactivate Bugzilla by clear the text that you put into the
+   :param:`shutdownhtml` parameter.
+
+#. Run another :ref:`sanity-check` on your
+   upgraded Bugzilla. It is recommended that you fix any problems
+   you see immediately. Failure to do this may mean that Bugzilla
+   may not work entirely correctly. 

diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
index 6910c648069c8a2d7b8b296f220ae4d3c7e36832..c38f28a2b0e368ae78351b78da7b2cdfeb18d45e 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
+++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
@@ -7,8 +7,24 @@ If you are unable (or unwilling) to use Git, another option is to obtain a
 tarball of the latest version from our website and upgrade your Bugzilla
 installation using that.
 
-Download Bugzilla
-=================
+Without a source code management system to help you, the process may be
+trickier.
+
+.. include:: upgrading-with-1.rst.inc
+
+As you are using a tarball and not an SCM, it's not at all easy to see if
+you've made local code customizations. You may have to use institutional
+knowledge, or download a fresh copy of your *current* version of Bugzilla
+and compare the two directories. If you find that you have, you'll need
+to turn them into a patch file, perhaps by diffing the two directories,
+and then reapply that patch file later. If you are customizing Bugzilla
+locally, please consider
+:ref:`rebasing your install on top of git <migrating-from-a-tarball>`.
+
+.. _upgrade-files-tarball:
+
+Getting The New Bugzilla
+========================
 
 Download a copy of the latest version of Bugzilla from the
 `Download Page <http://www.bugzilla.org/download/>`_ into a separate
@@ -16,9 +32,43 @@ directory (which we will call :file:`bugzilla-new`) alongside your existing
 Bugzilla installation (which we will assume is in a directory called
 :file:`bugzilla`).
 
-.. |diffcommand|   replace:: :command:`diff -u > patch.diff`
-.. |extstatusinfo| replace:: With no SCM to help you, you will have to
-                             work out by hand which extensions came with
-                             Bugzilla and which you added.
+Copy Across Data and Modules
+============================
+
+Copy the contents of the following directories from your current installation
+of Bugzilla into the corresponding directory in :file:`bugzilla-new/`:
+
+.. code-block:: none
+
+  lib/
+  data/
+  template/en/custom (may or may not exist)
+
+You also need to copy any extensions you have written or installed, which are
+in the :file:`extensions/` directory. Bugzilla ships with some extensions,
+so again if you want to know if any of the installed extensions are yours,
+you may have to compare with a clean copy of your current version. You can
+disregard any which have a :file:`disabled` file - those are not enabled.
+
+Lastly, copy the following file from your current installation of Bugzilla
+into the corresponding place in :file:`bugzilla-new/`:
+
+.. code-block:: none
+
+  localconfig
+
+This file contains your database password and access details.
+
+Swap The New Version In
+=======================
+
+Now we swap the directories over. From the directory containing the
+:file:`bugzilla` and :file:`bugzilla-new` directories, run:
+
+:command:`mv bugzilla bugzilla-old`
+
+:command:`mv bugzilla-new bugzilla`
+
+:command:`cd bugzilla`
 
-.. include:: upgrading-from-2.rst.inc
+.. include:: upgrading-with-2.rst.inc

diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst
index 6bcf29f15cbe9b1f662ea770e2ed70c81d81a5b6..1d9ba92f3dfc3f7ce73808698c1a2edc3a1eb161 100644 (file)
--- a/docs/en/rst/upgrading/upgrading-with-git.rst
+++ b/docs/en/rst/upgrading/upgrading-with-git.rst
@@ -9,50 +9,21 @@ intermediate steps. There is a script named :file:`checksetup.pl` included
 with Bugzilla that will automatically do all of the database migration
 for you.
 
-.. _upgrade-before:
+.. include:: upgrading-with-1.rst.inc
 
-Before You Upgrade
-==================
+You can see if you have local code customizations using:
 
-Before you start your upgrade, there are a few important
-steps to take:
+:command:`git diff`
 
-#. Read the
-   `Release Notes <http://www.bugzilla.org/releases/>`_ of the version you're
-   upgrading to and all intermediate versions, particularly the "Notes for
-   Upgraders" sections, if present. They may make you aware of additional
-   considerations.
+If that comes up empty, then run:
 
-#. Run the :ref:`sanity-check` on your installation. Attempt to fix all
-   warnings that the page produces before you start, or it's
-   possible that you may experience problems during your upgrade.
+:command:`git log | head`
 
-#. Work out how to :ref:`back up <backups>` your Bugzilla entirely, and
-   how to restore from a backup if need be.
+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.
 
-.. _upgrade-modified:
-
-Customized Bugzilla?
---------------------
-
-If you have modified the code or templates of your Bugzilla,
-then upgrading requires a bit more thought and effort than the simple process
-below. See :ref:`template-method` for a discussion of the various methods of
-customization that may have been used.
-
-The larger the jump you are trying to make, the more difficult it
-is going to be to upgrade if you have made local customizations.
-Upgrading from 4.2 to 4.2.1 should be fairly painless even if
-you are heavily customized, but going from 2.18 to 4.2 is going
-to mean a fair bit of work re-writing your local changes to use
-the new files, logic, templates, etc. If you have done no local
-changes at all, however, then upgrading should be approximately
-the same amount of work regardless of how long it has been since
-your version was released.
-
-You should do the upgrade on a test system with the same configuration and
-make sure all your customizations still work. If not, port and test them so
-you have them ready for the real thing.
+.. _start-upgrade-git:
 
 Starting the Upgrade
 ====================
@@ -62,11 +33,11 @@ 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`.
+#. 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:
+.. _upgrade-files-git:
 
 Getting The New Bugzilla
 ========================
@@ -82,34 +53,9 @@ in which Bugzilla is installed.
 
 .. todo:: What is the best way to pull latest stable?
 
-.. _upgrade-database:
-
-Upgrading the Database
-======================
-
-Run :file:`checksetup.pl`. This will do everything required to convert
-your existing database and settings to the new version.
-
-:command:`cd $BUGZILLA_HOME`
-
-:command:`./checksetup.pl`
-
-   .. warning:: For some upgrades, running :file:`checksetup.pl` on a large
-      installation (75,000 or more bugs) can take a long time,
-      possibly several hours, if e.g. indexes need to be rebuilt. If this
-      length of downtime would be a problem for you, you can determine
-      timings for your particular situation by doing a test upgrade on a
-      development server with the production data.
-
-.. _upgrade-finish:
-
-Finishing The Upgrade
-=====================
-
-#. Reactivate Bugzilla by clear the text that you put into the
-   :param:`shutdownhtml` parameter.
+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.
 
-#. Run another :ref:`sanity-check` on your
-   upgraded Bugzilla. It is recommended that you fix any problems
-   you see immediately. Failure to do this may mean that Bugzilla
-   may not work entirely correctly. 
+.. include:: upgrading-with-2.rst.inc

diff --git a/docs/en/rst/using.rst b/docs/en/rst/using.rst
deleted file mode 100644 (file)
index b6f9e03..0000000
--- a/docs/en/rst/using.rst
+++ /dev/null
@@ -1,18 +0,0 @@
-.. _using:
-
-==============
-Using Bugzilla
-==============
-
-.. toctree::
-   :maxdepth: 2
-
-   using/creating-an-account
-   using/filing
-   using/understanding
-   using/editing
-   using/finding
-   using/reports-and-charts
-   using/tips
-   using/preferences
-

diff --git a/docs/en/rst/using/index.rst b/docs/en/rst/using/index.rst
new file mode 100644 (file)
index 0000000..a877755
--- /dev/null
+++ b/docs/en/rst/using/index.rst
@@ -0,0 +1,18 @@
+.. _using:
+
+==============
+Using Bugzilla
+==============
+
+.. toctree::
+   :maxdepth: 2
+
+   creating-an-account
+   filing
+   understanding
+   editing
+   finding
+   reports-and-charts
+   tips
+   preferences
+