Work in progress.

diff --git a/docs/en/rst/about/credits.rst b/docs/en/rst/about/credits.rst
new file mode 100644 (file)
index 0000000..cce2713
--- /dev/null
+++ b/docs/en/rst/about/credits.rst
@@ -0,0 +1,46 @@
+.. _credits:
+
+Credits
+#######
+
+The people listed below have made enormous contributions to the
+creation of this Guide, through their writing, dedicated hacking efforts,
+numerous e-mail and IRC support sessions, and overall excellent
+contribution to the Bugzilla community:
+
+Gervase Markham
+    for entirely rewriting the documentation for Bugzilla 5.0.
+
+Matthew P. Barnson
+    for the Herculean task of pulling together the Bugzilla Guide
+    and shepherding it to 2.14.
+
+Terry Weissman
+    for initially writing Bugzilla and creating the README upon
+    which the UNIX installation documentation is largely based.
+
+Tara Hernandez
+    for keeping Bugzilla development going strong after Terry left
+    mozilla.org and for running landfill.
+
+Dave Lawrence
+    for providing insight into the key differences between Red
+    Hat's customized Bugzilla and stock Bugzilla.
+
+Dawn Endico
+    for being a hacker extraordinaire and putting up with Matthew's
+    incessant questions and arguments on irc.mozilla.org in #mozwebtools
+
+Jacob Steenhagen
+    for taking over documentation during the 2.17 development
+    period.
+
+Dave Miller
+    for taking over as project lead when Tara stepped down and
+    continually pushing for the documentation to be the best it can be.
+
+Thanks also go to the following people for significant contributions
+to this documentation:
+Kevin Brannen, Vlad Dascalu, Ben FrantzDale, Eric Hanson, Zach Lipton,
+Andrew Pearson, Joe Robins, Spencer Smith, Ron Teitelbaum, Shane Travis,
+Martin Wulffeld.

diff --git a/docs/en/rst/about/document-conventions.rst b/docs/en/rst/about/document-conventions.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/about/evaluating.rst b/docs/en/rst/about/evaluating.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/about/getting-help.rst b/docs/en/rst/about/getting-help.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/about/introduction.rst b/docs/en/rst/about/introduction.rst
new file mode 100644 (file)
index 0000000..e69de29

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

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

diff --git a/docs/en/rst/administering/flags.rst b/docs/en/rst/administering/flags.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/groups.rst b/docs/en/rst/administering/groups.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/keywords.rst b/docs/en/rst/administering/keywords.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/preferences.rst b/docs/en/rst/administering/preferences.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/products.rst b/docs/en/rst/administering/products.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/users.rst b/docs/en/rst/administering/users.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/versions-and-milestones.rst b/docs/en/rst/administering/versions-and-milestones.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/whining.rst b/docs/en/rst/administering/whining.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/administering/workflow.rst b/docs/en/rst/administering/workflow.rst
new file mode 100644 (file)
index 0000000..e69de29

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

diff --git a/docs/en/rst/customizing/existing-parameters.rst b/docs/en/rst/customizing/existing-parameters.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/customizing/extensions.rst b/docs/en/rst/customizing/extensions.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/customizing/languages.rst b/docs/en/rst/customizing/languages.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/customizing/skins.rst b/docs/en/rst/customizing/skins.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/customizing/templates.rst b/docs/en/rst/customizing/templates.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/customizing/who-can-change-what.rst b/docs/en/rst/customizing/who-can-change-what.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/customizing/writing-extensions.rst b/docs/en/rst/customizing/writing-extensions.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/extensions/example.rst b/docs/en/rst/extensions/example.rst
new file mode 100644 (file)
index 0000000..07b3558
--- /dev/null
+++ b/docs/en/rst/extensions/example.rst
@@ -0,0 +1,22 @@
+Example
+#######
+
+This is a sample documentation file for the Example extension. Like all of
+the Bugzilla docs, it's written in
+`reStructured Text (reST) format <http://sphinx-doc.org/latest/rest.html>`_
+and will be compiled by `Sphinx <http://sphinx-doc.org/>`_.
+
+If you build the docs yourself using :file:`makedocs.pl`, this file will get
+incorporated into the Extensions chapter, as will any documentation
+you write for your extensions which fulfils the following criteria:
+
+* In the :file:`extensions/YourExtension/doc/` directory
+* Has a :file:`.rst` file extension
+
+You are recommended to make the name of your reST doc file the same as the
+name of your extension, so that there is no clash when all the extension
+documentation is copied into the same directory. So, for example, this file
+is called :file:`example.rst`, as it's part of the Example extension. If you
+need multiple documentation files, prefix the filename with the name of your
+extension, e.g. :file:`example-extra.rst`.
+ 

diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst
index f2bd14f18b0f7ba986636d78b120b8d494a8b2af..c7e65d71d0fbafffda1a1732564b7b9784ab7b50 100644 (file)
--- a/docs/en/rst/index.rst
+++ b/docs/en/rst/index.rst
@@ -1,8 +1,3 @@
-.. Bugzilla documentation master file, created by
-   sphinx-quickstart on Tue Sep  3 16:11:00 2013.
-   You can adapt this file completely to your liking, but it should at least
-   contain the root `toctree` directive.
-
 Bugzilla Documentation
 ======================
 
@@ -11,13 +6,10 @@ Bugzilla Documentation
    :numbered:
 
    about
-   installation
-   administration
-   security
+   installing
+   upgrading
+   maintaining
+   customizing
+   integrating
+   administering
    using
-   extensions
-   customization
-   patches
-   troubleshooting
-   modules
-   gfdl

diff --git a/docs/en/rst/installation.rst b/docs/en/rst/installing.rst
similarity index 99%
rename from docs/en/rst/installation.rst
rename to docs/en/rst/installing.rst
index ef7423d2de7e012dea497a71e93668d9ad35ce90..4aca12176cc9c320f4bc241fa1040970d62aedf1 100644 (file)
--- a/docs/en/rst/installation.rst
+++ b/docs/en/rst/installing.rst
@@ -127,22 +127,7 @@ PostgreSQL server is started when the machine boots.
 Oracle
 ------
 
-Installed Version Test:
-
-.. code-block:: sql
-
-    SELECT * FROM v$version
-
-(you first have to log in into your DB)
-
-If you don't have it and your OS doesn't provide official packages,
-visit `<http://www.oracle.com/>`_. You need Oracle
-version 10.02.0 or higher.
-
-If you install from something other than a packaging/installation
-system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe
-(Windows Executable), or .msi (Windows Installer), make sure the
-Oracle server is started when the machine boots.
+XXX Need to replace instructions for Oracle
 
 .. _install-webserver:
 

diff --git a/docs/en/rst/installing/email.rst b/docs/en/rst/installing/email.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/installing/mac-os-x.rst b/docs/en/rst/installing/mac-os-x.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/installing/migrating.rst b/docs/en/rst/installing/migrating.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/installing/moving.rst b/docs/en/rst/installing/moving.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/installing/optional-features.rst b/docs/en/rst/installing/optional-features.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/installing/windows.rst b/docs/en/rst/installing/windows.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/integrating.rst b/docs/en/rst/integrating.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/integrating/apis.rst b/docs/en/rst/integrating/apis.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/integrating/tips.rst b/docs/en/rst/integrating/tips.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/maintaining.rst b/docs/en/rst/maintaining.rst
new file mode 100644 (file)
index 0000000..532bf97
--- /dev/null
+++ b/docs/en/rst/maintaining.rst
@@ -0,0 +1,5 @@
+Maintaining Bugzilla
+====================
+
+.. toctree::
+   :maxdepth: 2

diff --git a/docs/en/rst/maintaining/backups.rst b/docs/en/rst/maintaining/backups.rst
new file mode 100644 (file)
index 0000000..039dbaf
--- /dev/null
+++ b/docs/en/rst/maintaining/backups.rst
@@ -0,0 +1,16 @@
+.. _backups:
+
+Making Backups
+##############
+
+   Here are some sample commands you could use to backup
+   your database, depending on what database system you're
+   using. You may have to modify these commands for your
+   particular setup.
+
+   MySQL:
+       mysqldump --opt -u bugs -p bugs > bugs.sql
+   PostgreSQL:
+       pg_dump --no-privileges --no-owner -h localhost -U bugs
+       > bugs.sql
+

diff --git a/docs/en/rst/maintaining/merging-accounts.rst b/docs/en/rst/maintaining/merging-accounts.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/maintaining/sanity-check.rst b/docs/en/rst/maintaining/sanity-check.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/modules.rst b/docs/en/rst/modules.rst
deleted file mode 100644 (file)
index 4740161..0000000
--- a/docs/en/rst/modules.rst
+++ /dev/null
@@ -1,126 +0,0 @@
-.. highlight:: console
-
-.. _install-perlmodules-manual:
-
-===================================
-Manual Installation of Perl Modules
-===================================
-
-.. _modules-manual-instructions:
-
-Instructions
-############
-
-If you need to install Perl modules manually, here's how it's done.
-Download the module using the link given in the next section, and then
-apply this magic incantation, as root:
-
-::
-
-    # tar -xzvf <module>.tar.gz
-    # cd <module>
-    # perl Makefile.PL
-    # make
-    # make test
-    # make install
-
-.. note:: In order to compile source code under Windows you will need to obtain
-   a 'make' utility.  The :command:`nmake` utility provided with
-   Microsoft Visual C++ may be used.  As an alternative, there is a
-   utility called :command:`dmake` available from CPAN which is
-   written entirely in Perl.
-   As described in :ref:`modules-manual-download`, however, most
-   packages already exist and are available from ActiveState or theory58S.
-   We highly recommend that you install them using the ppm GUI available with
-   ActiveState and to add the theory58S repository to your list of repositories.
-
-.. _modules-manual-download:
-
-Download Locations
-##################
-
-.. note:: Running Bugzilla on Windows requires the use of ActiveState
-   Perl |min-perl-ver| or higher. Many modules already exist in the core
-   distribution of ActiveState Perl. Additional modules can be downloaded
-   from `<http://cpan.uwinnipeg.ca/PPMPackages/10xx/>`_
-   if you use Perl |min-perl-ver|.
-
-CGI:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/CGI.pm/>`_
-* Documentation: `<http://perldoc.perl.org/CGI.html>`_
-
-Data-Dumper:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/Data-Dumper/>`_
-* Documentation: `<http://search.cpan.org/dist/Data-Dumper/Dumper.pm>`_
-
-Date::Format (part of TimeDate):
-
-* CPAN Download Page: `<http://search.cpan.org/dist/TimeDate/>`_
-* Documentation: `<http://search.cpan.org/dist/TimeDate/lib/Date/Format.pm>`_
-
-DBI:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/DBI/>`_
-* Documentation: `<http://dbi.perl.org/docs/>`_
-
-DBD::mysql:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/DBD-mysql/>`_
-* Documentation: `<http://search.cpan.org/dist/DBD-mysql/lib/DBD/mysql.pm>`_
-
-DBD::Pg:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/DBD-Pg/>`_
-* Documentation: `<http://search.cpan.org/dist/DBD-Pg/Pg.pm>`_
-
-Template-Toolkit:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/Template-Toolkit/>`_
-* Documentation: `<http://www.template-toolkit.org/docs.html>`_
-
-GD:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/GD/>`_
-* Documentation: `<http://search.cpan.org/dist/GD/GD.pm>`_
-
-Template::Plugin::GD:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/Template-GD/>`_
-* Documentation: `<http://www.template-toolkit.org/docs/aqua/Modules/index.html>`_
-
-MIME::Parser (part of MIME-tools):
-
-* CPAN Download Page: `<http://search.cpan.org/dist/MIME-tools/>`_
-* Documentation: `<http://search.cpan.org/dist/MIME-tools/lib/MIME/Parser.pm>`_
-
-.. _modules-manual-optional:
-
-Optional Modules
-################
-
-Chart::Lines:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/Chart/>`_
-* Documentation: `<http://search.cpan.org/dist/Chart/Chart.pod>`_
-
-GD::Graph:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/GDGraph/>`_
-* Documentation: `<http://search.cpan.org/dist/GDGraph/Graph.pm>`_
-
-GD::Text::Align (part of GD::Text::Util):
-
-* CPAN Download Page: `<http://search.cpan.org/dist/GDTextUtil/>`_
-* Documentation: `<http://search.cpan.org/dist/GDTextUtil/Text/Align.pm>`_
-
-XML::Twig:
-
-* CPAN Download Page: `<http://search.cpan.org/dist/XML-Twig/>`_
-* Documentation: `<http://standards.ieee.org/resources/spasystem/twig/twig_stable.html>`_
-
-PatchReader:
-
-* CPAN Download Page: `<http://search.cpan.org/author/JKEISER/PatchReader/>`_
-* Documentation: `<http://www.johnkeiser.com/mozilla/Patch_Viewer.html>`_

diff --git a/docs/en/rst/patches.rst b/docs/en/rst/patches.rst
deleted file mode 100644 (file)
index 688d171..0000000
--- a/docs/en/rst/patches.rst
+++ /dev/null
@@ -1,88 +0,0 @@
-
-
-.. _patches:
-
-=======
-Contrib
-=======
-
-There are a number of unofficial Bugzilla add-ons in the
-:file:`$BUGZILLA_ROOT/contrib/`
-directory. This section documents them.
-
-.. _cmdline:
-
-Command-line Search Interface
-#############################
-
-There are a suite of Unix utilities for searching Bugzilla from the
-command line. They live in the
-:file:`contrib/cmdline` directory.
-There are three files - :file:`query.conf`,
-:file:`buglist` and :file:`bugs`.
-
-.. warning:: These files pre-date the templatization work done as part of the
-   2.16 release, and have not been updated.
-
-:file:`query.conf` contains the mapping from
-options to field names and comparison types. Quoted option names
-are ``grepped`` for, so it should be easy to edit this
-file. Comments (#) have no effect; you must make sure these lines
-do not contain any quoted ``option``.
-
-:file:`buglist` is a shell script that submits a
-Bugzilla query and writes the resulting HTML page to stdout.
-It supports both short options, (such as ``-Afoo``
-or ``-Rbar``) and long options (such
-as ``--assignedto=foo`` or ``--reporter=bar``).
-If the first character of an option is not ``-``, it is
-treated as if it were prefixed with ``--default=``.
-
-The column list is taken from the COLUMNLIST environment variable.
-This is equivalent to the ``Change Columns`` option
-that is available when you list bugs in buglist.cgi. If you have
-already used Bugzilla, grep for COLUMNLIST in your cookies file
-to see your current COLUMNLIST setting.
-
-:file:`bugs` is a simple shell script which calls
-:file:`buglist` and extracts the
-bug numbers from the output. Adding the prefix
-``http://bugzilla.mozilla.org/buglist.cgi?bug_id=``
-turns the bug list into a working link if any bugs are found.
-Counting bugs is easy. Pipe the results through
-:command:`sed -e 's/,/ /g' | wc | awk '{printf $2 "\\n"}'`
-
-Akkana Peck says she has good results piping
-:file:`buglist` output through
-:command:`w3m -T text/html -dump`
-
-.. _cmdline-bugmail:
-
-Command-line 'Send Unsent Bug-mail' tool
-########################################
-
-Within the :file:`contrib` directory
-exists a utility with the descriptive (if compact) name
-of :file:`sendunsentbugmail.pl`. The purpose of this
-script is, simply, to send out any bug-related mail that should
-have been sent by now, but for one reason or another has not.
-
-To accomplish this task, :file:`sendunsentbugmail.pl` uses
-the same mechanism as the :file:`sanitycheck.cgi` script;
-it scans through the entire database looking for bugs with changes that
-were made more than 30 minutes ago, but where there is no record of
-anyone related to that bug having been sent mail. Having compiled a list,
-it then uses the standard rules to determine who gets mail, and sends it
-out.
-
-As the script runs, it indicates the bug for which it is currently
-sending mail; when it has finished, it gives a numerical count of how
-many mails were sent and how many people were excluded. (Individual
-user names are not recorded or displayed.) If the script produces
-no output, that means no unsent mail was detected.
-
-*Usage*: move the sendunsentbugmail.pl script
-up into the main directory, ensure it has execute permission, and run it
-from the command line (or from a cron job) with no parameters.
-
-

diff --git a/docs/en/rst/troubleshooting.rst b/docs/en/rst/troubleshooting.rst
deleted file mode 100644 (file)
index 64b9263..0000000
--- a/docs/en/rst/troubleshooting.rst
+++ /dev/null
@@ -1,239 +0,0 @@
-.. highlight:: console
-
-.. _troubleshooting:
-
-===============
-Troubleshooting
-===============
-
-This section gives solutions to common Bugzilla installation
-problems. If none of the section headings seems to match your
-problem, read the general advice.
-
-.. _general-advice:
-
-General Advice
-##############
-
-If you can't get :file:`checksetup.pl` to run to
-completion, it normally explains what's wrong and how to fix it.
-If you can't work it out, or if it's being uncommunicative, post
-the errors in the
-`mozilla.support.bugzilla <news://news.mozilla.org/mozilla.support.bugzilla>`_
-newsgroup.
-
-If you have made it all the way through
-:ref:`installation` (Installation) and
-:ref:`configuration` (Configuration) but accessing the Bugzilla
-URL doesn't work, the first thing to do is to check your web server error
-log. For Apache, this is often located at
-:file:`/etc/logs/httpd/error_log`. The error messages
-you see may be self-explanatory enough to enable you to diagnose and
-fix the problem. If not, see below for some commonly-encountered
-errors. If that doesn't help, post the errors to the newsgroup.
-
-Bugzilla can also log all user-based errors (and many code-based errors)
-that occur, without polluting the web server's error log.  To enable
-Bugzilla error logging, create a file that Bugzilla can write to, named
-:file:`errorlog`, in the Bugzilla :file:`data`
-directory.  Errors will be logged as they occur, and will include the type
-of the error, the IP address and username (if available) of the user who
-triggered the error, and the values of all environment variables; if a
-form was being submitted, the data in the form will also be included.
-To disable error logging, delete or rename the
-:file:`errorlog` file.
-
-.. _trbl-testserver:
-
-The Apache web server is not serving Bugzilla pages
-###################################################
-
-After you have run :command:`checksetup.pl` twice,
-run :command:`testserver.pl http://yoursite.yourdomain/yoururl`
-to confirm that your web server is configured properly for
-Bugzilla.
-
-::
-
-    $ ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip
-    TEST-OK Webserver is running under group id in $webservergroup.
-    TEST-OK Got ant picture.
-    TEST-OK Webserver is executing CGIs.
-    TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig.
-
-.. _trbl-perlmodule:
-
-I installed a Perl module, but :file:`checksetup.pl` claims it's not installed!
-###############################################################################
-
-This could be caused by one of two things:
-
-#. You have two versions of Perl on your machine. You are installing
-   modules into one, and Bugzilla is using the other. Rerun the CPAN
-   commands (or manual compile) using the full path to Perl from the
-   top of :file:`checksetup.pl`. This will make sure you
-   are installing the modules in the right place.
-
-#. The permissions on your library directories are set incorrectly.
-   They must, at the very least, be readable by the web server user or
-   group. It is recommended that they be world readable.
-
-.. _trbl-dbdSponge:
-
-DBD::Sponge::db prepare failed
-##############################
-
-The following error message may appear due to a bug in DBD::mysql
-(over which the Bugzilla team have no control):
-
-::
-
-    DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248.
-    SV = NULL(0x0) at 0x20fc444
-    REFCNT = 1
-    FLAGS = (PADBUSY,PADMY)
-
-To fix this, go to
-:file:`<path-to-perl>/lib/DBD/sponge.pm`
-in your Perl installation and replace
-
-.. code-block:: perl
-
-    my $numFields;
-    if ($attribs->{'NUM_OF_FIELDS'}) {
-        $numFields = $attribs->{'NUM_OF_FIELDS'};
-    }
-    elsif ($attribs->{'NAME'}) {
-        $numFields = @{$attribs->{NAME}};
-    }
-
-with
-
-.. code-block:: perl
-
-    my $numFields;
-    if ($attribs->{'NUM_OF_FIELDS'}) {
-        $numFields = $attribs->{'NUM_OF_FIELDS'};
-    }
-    elsif ($attribs->{'NAMES'}) {
-        $numFields = @{$attribs->{NAMES}};
-    }
-
-(note the S added to NAME.)
-
-.. _paranoid-security:
-
-cannot chdir(/var/spool/mqueue)
-###############################
-
-If you are installing Bugzilla on SuSE Linux, or some other
-distributions with ``paranoid`` security options, it is
-possible that the checksetup.pl script may fail with the error:
-::
-
-    cannot chdir(/var/spool/mqueue): Permission denied
-
-This is because your :file:`/var/spool/mqueue`
-directory has a mode of ``drwx------``.
-Type :command:`chmod 755 :file:`/var/spool/mqueue``
-as root to fix this problem. This will allow any process running on your
-machine the ability to *read* the
-:file:`/var/spool/mqueue` directory.
-
-.. _trbl-relogin-everyone:
-
-Everybody is constantly being forced to relogin
-###############################################
-
-The most-likely cause is that the ``cookiepath`` parameter
-is not set correctly in the Bugzilla configuration.  You can change this (if
-you're a Bugzilla administrator) from the editparams.cgi page via the web interface.
-
-The value of the cookiepath parameter should be the actual directory
-containing your Bugzilla installation, *as seen by the end-user's
-web browser*. Leading and trailing slashes are mandatory. You can
-also set the cookiepath to any directory which is a parent of the Bugzilla
-directory (such as '/', the root directory). But you can't put something
-that isn't at least a partial match or it won't work. What you're actually
-doing is restricting the end-user's browser to sending the cookies back only
-to that directory.
-
-How do you know if you want your specific Bugzilla directory or the
-whole site?
-
-If you have only one Bugzilla running on the server, and you don't
-mind having other applications on the same server with it being able to see
-the cookies (you might be doing this on purpose if you have other things on
-your site that share authentication with Bugzilla), then you'll want to have
-the cookiepath set to "/", or to a sufficiently-high enough directory that
-all of the involved apps can see the cookies.
-
-.. _trbl-relogin-everyone-share:
-
-Examples of urlbase/cookiepath pairs for sharing login cookies
-==============================================================
-
-|    urlbase is http://bugzilla.mozilla.org/
-|    cookiepath is /
-
-
-|    urlbase is http://tools.mysite.tld/bugzilla/
-|    but you have http://tools.mysite.tld/someotherapp/ which shares
-|    authentication with your Bugzilla
-|
-|    cookiepath is /
-
-On the other hand, if you have more than one Bugzilla running on the
-server (some people do - we do on landfill) then you need to have the
-cookiepath restricted enough so that the different Bugzillas don't
-confuse their cookies with one another.
-
-.. _trbl-relogin-everyone-restrict:
-
-Examples of urlbase/cookiepath pairs to restrict the login cookie
-=================================================================
-
-|    urlbase is http://landfill.bugzilla.org/bugzilla-tip/
-|    cookiepath is /bugzilla-tip/
-
-|    urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/
-|    cookiepath is /bugzilla-4.0-branch/
-
-If you had cookiepath set to ``/`` at any point in the
-past and need to set it to something more restrictive
-(i.e. ``/bugzilla/``), you can safely do this without
-requiring users to delete their Bugzilla-related cookies in their
-browser (this is true starting with Bugzilla 2.18 and Bugzilla 2.16.5).
-
-.. _trbl-index:
-
-:file:`index.cgi` doesn't show up unless specified in the URL
-#############################################################
-
-You probably need to set up your web server in such a way that it
-will serve the index.cgi page as an index page.
-
-If you are using Apache, you can do this by adding
-:file:`index.cgi` to the end of the
-``DirectoryIndex`` line
-as mentioned in :ref:`http-apache`.
-
-.. _trbl-passwd-encryption:
-
-checksetup.pl reports "Client does not support authentication protocol requested by server..."
-##############################################################################################
-
-This error is occurring because you are using the new password
-encryption that comes with MySQL 4.1, while your
-:file:`DBD::mysql` module was compiled against an
-older version of MySQL. If you recompile :file:`DBD::mysql`
-against the current MySQL libraries (or just obtain a newer version
-of this module) then the error may go away.
-
-If that does not fix the problem, or if you cannot recompile the
-existing module (e.g. you're running Windows) and/or don't want to
-replace it (e.g. you want to keep using a packaged version), then a
-workaround is available from the MySQL docs:
-`<http://dev.mysql.com/doc/mysql/en/Old_client.html>`_
-
-

diff --git a/docs/en/rst/upgrading.rst b/docs/en/rst/upgrading.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/upgrading/overview.rst b/docs/en/rst/upgrading/overview.rst
new file mode 100644 (file)
index 0000000..297d63c
--- /dev/null
+++ b/docs/en/rst/upgrading/overview.rst
@@ -0,0 +1,42 @@
+Overview
+########
+
+You can upgrade Bugzilla from any version to any later version in one go -
+there is no need to pass through intermediate versions unless you are changing
+the method by which you obtain the code along the way.
+ 
+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 you, 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
+upgrade in three steps:
+
+1. upgrade to the latest point release of your current Bugzilla version;
+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.
+
+Some Bugzillas were installed simply by downloading a copy of the code as
+an archive file ("tarball"). However, recent tarballs have included source
+code management system information, so you may be able to use the Git, Bzr
+or CVS instructions.
+
+If you aren't sure which of these categories you fall into, to find out which
+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`
+
+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
+a tarball. See :ref:`upgrading-with-a-tarball`.
+
+Before performing any upgrade, it's a good idea to back up both your Bugzilla
+directory and your database. XXXlink to backup info in Maintenance

diff --git a/docs/en/rst/upgrading/upgrading-from-a-tarball.rst b/docs/en/rst/upgrading/upgrading-from-a-tarball.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/upgrading-from-bazaar.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/upgrading-from-cvs.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
new file mode 100644 (file)
index 0000000..9a41ba7
--- /dev/null
+++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst
@@ -0,0 +1,45 @@
+.. _upgrading-with-a-tarball:
+
+Upgrading with a Tarball
+########################
+
+If you are unable (or unwilling) to use Bzr, another option that's
+always available is to obtain the latest tarball from the `Download Page <http://www.bugzilla.org/download/>`_ and
+create a new Bugzilla installation from that.
+
+This sequence of commands shows how to get the tarball from the
+command-line; it is also possible to download it from the site
+directly in a web browser. If you go that route, save the file
+to the :file:`/var/www/html`
+directory (or its equivalent, if you use something else) and
+omit the first three lines of the example.
+
+::
+
+    $ cd /var/www/html
+    $ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2.1.tar.gz
+    ...
+    $ tar xzvf bugzilla-4.2.1.tar.gz
+    bugzilla-4.2.1/
+    bugzilla-4.2.1/colchange.cgi
+    ...
+    $ cd bugzilla-4.2.1
+    $ cp ../bugzilla/localconfig* .
+    $ cp -r ../bugzilla/data .
+    $ cd ..
+    $ mv bugzilla bugzilla.old
+    $ mv bugzilla-4.2.1 bugzilla
+
+.. warning:: The :command:`cp` commands both end with periods which
+   is a very important detail--it means that the destination
+   directory is the current working directory.
+
+.. warning:: If you have some extensions installed, you will have to copy them
+   to the new bugzilla directory too. Extensions are located in :file:`bugzilla/extensions/`.
+   Only copy those you
+   installed, not those managed by the Bugzilla team.
+
+This upgrade method will give you a clean install of Bugzilla.
+That's fine if you don't have any local customizations that you
+want to maintain. If you do have customizations, then you will
+need to reapply them by hand to the appropriate files.

diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/using/creating-an-account.rst b/docs/en/rst/using/creating-an-account.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/using/editing.rst b/docs/en/rst/using/editing.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/using/filing.rst b/docs/en/rst/using/filing.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/using/finding.rst b/docs/en/rst/using/finding.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/using/preferences.rst b/docs/en/rst/using/preferences.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/using/tips.rst b/docs/en/rst/using/tips.rst
new file mode 100644 (file)
index 0000000..e69de29

diff --git a/docs/en/rst/using/understanding.rst b/docs/en/rst/using/understanding.rst
new file mode 100644 (file)
index 0000000..e69de29