Continued WIP

git-svn-id: svn://10.0.0.236/trunk@265703 18797224-902f-48f8-a5cc-f745e15eee43

mozilla/webtools/bugzilla/.bzrrev

@@ -1 +1 @@
-9232
+9233

mozilla/webtools/bugzilla/.gitrev

@@ -1 +1 @@
-3fb5117632fd04f336068279871c0559c5dce554
+715ec3d7af9693f40aa578391900b093c8c078bb

mozilla/webtools/bugzilla/docs/en/rst/about/credits.rst

@@ -3,44 +3,25 @@
 Credits
 #######
 
-The people listed below have made enormous contributions to the
+The people listed below have made significant contributions to the
-creation of this Guide, through their writing, dedicated hacking efforts,
+creation of this documentation:
-numerous e-mail and IRC support sessions, and overall excellent
-contribution to the Bugzilla community:
 
-Gervase Markham
+Andrew Pearson,
-    for entirely rewriting the documentation for Bugzilla 5.0.
+Ben FrantzDale,
-
+Dave Lawrence,
-Matthew P. Barnson
+Dave Miller,
-    for the Herculean task of pulling together the Bugzilla Guide
+Dawn Endico,
-    and shepherding it to 2.14.
+Eric Hanson,
-
+Gervase Markham,
-Terry Weissman
+Jacob Steenhagen,
-    for initially writing Bugzilla and creating the README upon
+Joe Robins,
-    which the UNIX installation documentation is largely based.
+Kevin Brannen,
-
+Martin Wulffeld,
-Tara Hernandez
+Matthew P. Barnson,
-    for keeping Bugzilla development going strong after Terry left
+Ron Teitelbaum,
-    mozilla.org and for running landfill.
+Shane Travis,
-
+Spencer Smith,
-Dave Lawrence
+Tara Hernandez,
-    for providing insight into the key differences between Red
+Terry Weissman,
-    Hat's customized Bugzilla and stock Bugzilla.
+Vlad Dascalu,
-
+Zach Lipton.
-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.

mozilla/webtools/bugzilla/docs/en/rst/about/document-conventions.rst

@@ -15,10 +15,6 @@ A filename or a path to a filename is displayed like this:
 A command to type in the shell is displayed like this:
 :command:`command --arguments`
 
-bash$ represents a normal user's prompt under bash shell
-
-bash# represents a root user's prompt under bash shell
-
 A sample of code is illustrated like this:
 
 ::
@@ -27,7 +23,8 @@ A sample of code is illustrated like this:
     Second Line of Code
     ...
 
-This documentation is maintained in reStructured Text format.
+This documentation is maintained in reStructured Text format using the
+`Sphinx <http://www.sphinx-doc.org/>`_ documentation system.
 Changes are best submitted as diffs, attached
 to a bug filed in the `Bugzilla Documentation <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
 component.

mozilla/webtools/bugzilla/docs/en/rst/about/introduction.rst

@@ -3,11 +3,10 @@
 Introduction
 ############
 
-This is the documentation for version |version| of Bugzilla, a
+This is the documentation for version |version| of Bugzilla, a bug-tracking
-bug-tracking system from mozilla.org.
+system from Mozilla. Bugzilla is an enterprise-class piece of software
-Bugzilla is an enterprise-class piece of software
+that tracks millions of bugs and issues for thousands of organizations around
-that tracks millions of bugs and issues for hundreds of
+the world.
-organizations around the world.
 
 The most current version of this document can always be found on the
 `Bugzilla Documentation Page <http://www.bugzilla.org/docs/>`_.

mozilla/webtools/bugzilla/docs/en/rst/installing.rst

@@ -9,13 +9,14 @@ Installing Bugzilla
 .. note:: If you just want to *use* Bugzilla,
    you do not need to install it. None of this chapter is relevant to
    you. Ask your Bugzilla administrator for the URL to access it from
-   your web browser.
+   your web browser. You may want to read :ref:`using`.
 
 Bugzilla can be installed under Linux, Windows, Mac OS X, and perhaps other
 operating systems. However, if you are setting it up on a dedicated machine
 and you have control of the operating system to use, the Bugzilla team
 wholeheartedly recommends Linux as an extremely versatile, stable, and robust
-operating system that provides an ideal environment for Bugzilla.
+operating system that provides an ideal environment for Bugzilla. In that
+case, you may want to read the :ref:`Quick Start instructions <quick-start>`.
 
 .. toctree::
    :maxdepth: 1
@@ -24,7 +25,6 @@ operating system that provides an ideal environment for Bugzilla.
    installing/linux
    installing/windows
    installing/mac-os-x
-   installing/email
+   installing/post-install-config
-   installing/optional-features
    installing/migrating
    installing/moving

mozilla/webtools/bugzilla/docs/en/rst/installing/apache.rst

@@ -4,7 +4,9 @@ Apache
 ######
 
 You have two options for running Bugzilla under Apache - mod_cgi (the
-default) and mod_perl. mod_perl is faster but takes more resources.
+default) and mod_perl. mod_perl is faster but takes more resources. You
+should probably only consider mod_perl if your Bugzilla is going to be heavily
+used.
 
 .. _http-apache-mod_cgi:
 
@@ -46,6 +48,8 @@ some global permissions.
    ``ScriptInterpreterSource Registry-Strict``
    line, see :ref:`Windows specific notes <win32-http>`.
 
+   XXX Does this link still work?
+
 .. _http-apache-mod_perl:
 
 Apache with mod_perl
@@ -53,6 +57,10 @@ Apache with mod_perl
 
 Bugzilla requires version 1.999022 (AKA 2.0.0-RC5) of mod_perl.
 
+XXX Is this relevant any more - how old is that version?
+
+XXX Can one use mod_perl on Windows?
+
 Some configuration is required to make Bugzilla work with Apache
 and mod_perl.
 
@@ -62,19 +70,21 @@ and mod_perl.
 #. Add the following information to your httpd.conf file, substituting
    where appropriate with your own local paths.
 
-   .. note:: This should be used instead of the <Directory> block
-      shown above. This should also be above any other ``mod_perl``
-      directives within the :file:`httpd.conf` and must be specified
-      in the order as below.
-
-   .. warning:: You should also ensure that you have disabled ``KeepAlive``
-      support in your Apache install when utilizing Bugzilla under mod_perl
-
    .. code-block:: apache
 
        PerlSwitches -w -T
        PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl
 
+   .. note:: This should be used instead of the <Directory> block
+      shown above. This should also be above any other ``mod_perl``
+      directives within the :file:`httpd.conf` and the directives must be
+      specified in the order above.
+
+   .. warning:: You should also ensure that you have disabled ``KeepAlive``
+      support in your Apache install when utilizing Bugzilla under mod_perl
+
+      XXX How?
+
 On restarting Apache, Bugzilla should now be running within the
 mod_perl environment.
 
@@ -89,11 +99,11 @@ under mod_perl:
 - Under mod_perl, you have to restart Apache if you make any manual change to
   any Bugzilla file. You can't just reload--you have to actually
   *restart* the server (as in make sure it stops and starts
-  again). You *can* change localconfig and the params file
+  again). You *can* change :file:`localconfig` and the :file:`params` file
   manually, if you want, because those are re-read every time you load a page.
 
 - You must run in Apache's Prefork MPM (this is the default). The Worker MPM
-  may not work--we haven't tested Bugzilla's mod_perl support under threads.
+  may not work -- we haven't tested Bugzilla's mod_perl support under threads.
   (And, in fact, we're fairly sure it *won't* work.)
 
 - Bugzilla generally expects to be the only mod_perl application running on

mozilla/webtools/bugzilla/docs/en/rst/installing/email.rst

@@ -8,22 +8,60 @@ here. The simplest is to get Gmail or some other email provider to do the
 work for you, but you can also hand the mail off to a local email server,
 or run one yourself on the Bugzilla machine.
 
+Bugzilla's approach to email is configured in the :guilabel:`Email` section
+of the Parameters.
+
+XXX Bug: description of mail_delivery_method talks about Qmail, and is in
+other ways wrong.
+
 .. _install-MTA:
 
-Mail Transfer Agent (MTA)
+Use Another Mail Server
-=========================
+=======================
 
-Bugzilla is dependent on the availability of an e-mail system for its
+This section corresponds to choosing a :guilabel:`mail_delivery_method` of
-user authentication and for other tasks.
+``SMTP``.
 
-.. note:: This is not entirely true.  It is possible to completely disable
+This method passes the email off to an existing mail server. Your
-   email sending, or to have Bugzilla store email messages in a
+organization may well already have one running for their internal email, and
-   file instead of sending them.  However, this is mainly intended
+may prefer to use it for confidentiality reasons. If so, you need the
-   for testing, as disabling or diverting email on a production
+following information about it:
-   machine would mean that users could miss important events (such
+
-   as bug changes or the creation of new accounts).
+* The domain name of the server (Parameter: :guilabel:`smtpserver`)
-   For more information, see the ``mail_delivery_method`` parameter
+* The username and password to use (Parameters: :guilabel:`smtp_username` and 
-   in :ref:`parameters`.
+  :guilabel:`smtp_password`)
+* Whether the server uses SSL (Parameter: :guilabel:`smtp_ssl`)
+* The address you should be sending mail 'From' (Parameter:
+  :guilabel:`mailfrom``)
+
+If your organization does not run its own mail server, you can use the
+services of one of any number of popular email providers.
+
+Gmail
+-----
+
+Visit https://gmail.com and create a new Gmail account for your Bugzilla to
+use. Then, set the following parameter values in the "Email" section:
+
+* :guilabel:`mail_delivery_method`: ``SMTP``
+* :guilabel:`mailfrom`: ``new_gmail_address@gmail.com``
+* :guilabel:`smtpserver`: ``smtp.gmail.com:465``
+* :guilabel:`smtp_username`: ``new_gmail_address@gmail.com``
+* :guilabel:`smtp_password`: ``new_gmail_password``
+* :guilabel:`smtp_ssl`: ``On``
+
+Run Your Own Mail Server
+========================
+
+This section corresponds to choosing a :guilabel:`mail_delivery_method` of
+``Sendmail``.
+
+XXX Do we still need this? Why would anyone want to do this in 2014?
+
+Unless you know what you are doing, and can deal with the possible problems
+of spam, bounces and blacklists, it is probably unwise to set up your own
+mail server just for Bugzilla. However, if you wish to do so, here is some
+guidance.
 
 On Linux, any Sendmail-compatible MTA (Mail Transfer Agent) will
 suffice.  Sendmail, Postfix, qmail and Exim are examples of common
@@ -32,11 +70,12 @@ configure, and therefore many people replace Sendmail with Postfix or
 Exim. They are drop-in replacements, so Bugzilla will not
 distinguish between them.
 
-If you are using Sendmail, version 8.7 or higher is required.
+If you are using Sendmail, version 8.7 or higher is required. If you are
-If you are using a Sendmail-compatible MTA, it must be congruent with
+using a Sendmail-compatible MTA, it must be compatible with at least version
-at least version 8.7 of Sendmail.
+8.7 of Sendmail.
 
-Consult the manual for the specific MTA you choose for detailed
+Detailed information on configuring an MTA is outside the scope of this
+document. Consult the manual for the specific MTA you choose for detailed
 installation instructions. Each of these programs will have their own
 configuration files where you must configure certain parameters to
 ensure that the mail is delivered properly. They are implemented

mozilla/webtools/bugzilla/docs/en/rst/installing/linux.rst

@@ -3,14 +3,21 @@
 Linux
 #####
 
-Many Linux distributions include Bugzilla and its dependencies in their
+Some Linux distributions include Bugzilla and its dependencies in their
 package management systems. If you have root access, installing Bugzilla on
 any Linux system could be as simple as finding the Bugzilla package in the
 package management application and installing it. There may be a small bit
-of additional configuration required. If you are installing the machine from
+of additional configuration required.
-scratch, :ref:`quick-start` may be the best instructions for you.
 
-XXX What's our current position on Debian/Ubuntu packages of Bugzilla?
+If you are installing your machine from scratch, :ref:`quick-start` may be
+the best instructions for you.
+
+XXX What's our current position on Debian/Ubuntu packages of Bugzilla? Are
+there any, and are they any good?
+
+XXX Which versions of RHEL have packages new enough for us to support them?
+
+XXX What's the right order for all these steps?
 
 Install Packages
 ================
@@ -77,6 +84,13 @@ until the end of the install.
 
 XXX Is this true, if they are installing modules locally?
 
+To check whether you have all the required modules and what is still missing,
+run:
+
+:command:`./checksetup.pl --check-modules`
+
+You can run this command as many times as necessary.
+
 Install all missing modules locally like this:
 
 :command:`./install-module.pl --all`
@@ -85,12 +99,6 @@ Or, you can pass an individual module name:
 
 :command:`./install-module.pl <modulename>`
 
-To check you indeed have new enough versions of all the required modules, run:
-
-:command:`./checksetup.pl --check-modules`
-
-You can run this command as many times as necessary.
-
 .. note:: If you are using a package-based distribution, and attempting to
    install the Perl modules from CPAN (e.g. by using
    :file:`install-module.pl`), you may need to install the "development"
@@ -99,28 +107,28 @@ You can run this command as many times as necessary.
    distribution you are using, but are often called
    :file:`<packagename>-devel`.
 
-.. _config-database:
+   XXX Give examples for Debian/Ubuntu and RedHat?
+
+.. _config-webserver:
 
 Web Server
 ==========
 
-We have instructions for configuring Apache and IIS, although we strongly
+Any web server that is capable of running CGI scripts can be made to work.
-recommend using Apache. However, pretty much any web server that is capable of
+We have specific instructions for the following:
-running CGI scripts will work.
 
 .. toctree::
    :maxdepth: 1
 
    apache
-   iis
-
-XXX Don't need IIS in the Linux docs.
 
 You can run :command:`testserver.pl http://bugzilla-url/` from the command
 line to check if your web server is correctly configured.
 
 XXX Does this work before doing any localconfig stuff?
 
+.. _config-database:
+
 Database Engine
 ===============
 
@@ -154,29 +162,27 @@ This file contains the default settings for a number of
 Bugzilla parameters, the most important of which are the group your web
 server runs as, and information on how to connect to your database.
 
-Load this file in your editor. The only two values you
+Load this file in your editor. You will need to check/change ``$db_driver``
-need to change are ``$db_driver`` and ``$db_pass``,
+and ``$db_pass``, which are respectively the type of the database you are
-respectively the type of the database and the password for
+using and the password for the ``bugs`` database user you have created.
-the user you will create for your database. Pick a strong
+``$db_driver`` can be either ``mysql``, ``Pg`` (PostgreSQL), ``Oracle`` or
-password (for simplicity, it should not contain single quote
+``Sqlite``. All values are case-sensitive.
-characters) and put it here. ``$db_driver`` can be either ``mysql``,
-``Pg``, ``Oracle`` or ``Sqlite`` (case-sensitive).
-
-.. note:: In Oracle, ``$db_name`` should actually be
-   the SID name of your database (e.g. "XE" if you are using Oracle XE).
 
 Set the value of ``$webservergroup`` to the group your web server runs as.
-The default is ``apache`` (correct for Red Hat/Fedora). On Debian and Ubuntu,
+The default is ``apache``, which is correct for Red Hat and Fedora. On Debian
-Apache uses the ``www-data`` group.
+and Ubuntu, the correct value is ``www-data``.
 
 The other options in the :file:`localconfig` file are documented by their
 accompanying comments. If you have a non-standard database setup, you may
 need to change one or more of the other ``$db_*`` parameters.
 
+.. note:: If you are using Oracle, ``$db_name`` should be set to
+   the SID name of your database (e.g. "XE" if you are using Oracle XE).
+
 checksetup.pl
 =============
 
-Next, run :file:`checksetup.pl` an additional. It reconfirms
+Next, run :file:`checksetup.pl` an additional time. It reconfirms
 that all the modules are present, and notices the altered
 localconfig file, which it assumes you have edited to your
 satisfaction. It compiles the UI templates,
@@ -206,16 +212,13 @@ you should see the Bugzilla front page.
    subdirectory or used a symbolic link from your web site root to
    the Bugzilla directory.
 
-Log in with the administrator account you defined in the last
+Next, do the :ref:`post-install-config`.
-:file:`checksetup.pl` run. You should go through
+
-the Parameters page and see if there are any you wish to change.
+XXXX How to we integrate the below (copied from the wiki)?
-They key parameters are documented in :ref:`parameters`;
+
-you should certainly alter
+Gentoo
-:command:`maintainer` and :command:`urlbase`;
+======
-you may also want to alter
-:command:`cookiepath` or :command:`requirelogin`.
 
-== Gentoo ==
 Gentoo pulls in all dependencies and, if you don't have the vhosts USE flag enabled, installs Bugzilla to /var/www/localhost/bugzilla when you issue:
 
 <code># emerge -av bugzilla</code>
@@ -232,7 +235,8 @@ Else:
 mysql>CREATE DATABASE databasename;<br />
 mysql>GRANT <privs> ON databasename.* to 'bugzillauser'@'hostname' identified by 'pa$$w0rd';</code>
  
-== Fedora ==
+Fedora
+======
 
 '''Please be aware of this:''' https://bugzilla.mozilla.org/show_bug.cgi?id=415605
 (Please remove this link once determined the RPM has been repaired)

mozilla/webtools/bugzilla/docs/en/rst/installing/migrating.rst

@@ -5,7 +5,7 @@ Migrating From Other Bug-Tracking Systems
 
 Bugzilla has a framework you can use for migrating from other bug-tracking
 systems -
-`Bugzilla::Migrate <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Migrate.html>_.
+`Bugzilla::Migrate <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Migrate.html>`_.
 It provides the infrastructure you will need,
 but requires a module to be written to define the specifics of the system you
 are coming from. One exists for

mozilla/webtools/bugzilla/docs/en/rst/installing/mysql.rst

@@ -38,13 +38,14 @@ command-line client and enter:
 
     FLUSH PRIVILEGES;
 
-The above permits an account called ``bugs``
+You need to replace ``$db_pass`` with a strong password you have chosen.
+Write that password down somewhere.
+
+The above command permits an account called ``bugs``
 to connect from the local machine, ``localhost``. Modify the command to
 reflect your setup if you will be connecting from another
 machine or as a different user.
 
-Make a note of the password you set.
-
 .. _mysql-max-allowed-packet:
 
 Allow large attachments and many comments
@@ -55,7 +56,11 @@ configuration file, which is usually :file:`/etc/my.cnf`
 on Linux.
 
 By default, MySQL will only allow you to insert things
-into the database that are smaller than 1MB. Bugzilla attachments
+into the database that are smaller than 1MB.
+
+XXX Is this still true? It's 16MB on Ubuntu 14.04...
+
+Bugzilla attachments
 may be larger than this. Also, Bugzilla combines all comments
 on a single bug into one field for full-text searching, and the
 combination of all comments on a single bug could in some cases
@@ -65,6 +70,8 @@ We recommend that you allow at least 16MB packets by
 adding the ``max_allowed_packet`` parameter to your MySQL
 configuration in the ``[mysqld]`` section, like this:
 
+XXX is "adding" right? Surely it's normally present?
+
 ::
 
     [mysqld]

mozilla/webtools/bugzilla/docs/en/rst/installing/optional-features.rst

@@ -1,157 +0,0 @@
-.. _optional-features:
-
-Optional Features
-#################
-
-XXXHACKME
-
-Bugzilla has a number of optional features. This section describes how
-to configure or enable them.
-
-Bug Graphs
-==========
-
-If you have installed the necessary Perl modules you
-can start collecting statistics for the nifty Bugzilla
-graphs.
-
-::
-
-    # crontab -e
-
-This should bring up the crontab file in your editor.
-Add a cron entry like this to run
-:file:`collectstats.pl`
-daily at 5 after midnight:
-
-.. code-block:: none
-
-    5 0 * * * cd <your-bugzilla-directory> && ./collectstats.pl
-
-After two days have passed you'll be able to view bug graphs from
-the Reports page.
-
-.. note:: Windows does not have 'cron', but it does have the Task
-   Scheduler, which performs the same duties. There are also
-   third-party tools that can be used to implement cron, such as
-   `nncron <http://www.nncron.ru/>`_.
-
-.. _installation-whining-cron:
-
-The Whining Cron
-================
-
-What good are
-bugs if they're not annoying? To help make them more so you
-can set up Bugzilla's automatic whining system to complain at engineers
-which leave their bugs in the CONFIRMED state without triaging them.
-
-This can be done by adding the following command as a daily
-crontab entry, in the same manner as explained above for bug
-graphs. This example runs it at 12.55am.
-
-.. code-block:: none
-
-    55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl
-
-.. note:: Windows does not have 'cron', but it does have the Task
-   Scheduler, which performs the same duties. There are also
-   third-party tools that can be used to implement cron, such as
-   `nncron <http://www.nncron.ru/>`_.
-
-.. _installation-whining:
-
-Whining
-=======
-
-As of Bugzilla 2.20, users can configure Bugzilla to regularly annoy
-them at regular intervals, by having Bugzilla execute saved searches
-at certain times and emailing the results to the user.  This is known
-as "Whining".  The process of configuring Whining is described
-in :ref:`whining`, but for it to work a Perl script must be
-executed at regular intervals.
-
-This can be done by adding the following command as a daily
-crontab entry, in the same manner as explained above for bug
-graphs. This example runs it every 15 minutes.
-
-.. code-block:: none
-
-    */15 * * * * cd <your-bugzilla-directory> && ./whine.pl
-
-.. note:: Whines can be executed as often as every 15 minutes, so if you specify
-   longer intervals between executions of whine.pl, some users may not
-   be whined at as often as they would expect.  Depending on the person,
-   this can either be a very Good Thing or a very Bad Thing.
-
-.. note:: Windows does not have 'cron', but it does have the Task
-   Scheduler, which performs the same duties. There are also
-   third-party tools that can be used to implement cron, such as
-   `nncron <http://www.nncron.ru/>`_.
-
-.. _apache-addtype:
-
-Serving Alternate Formats with the right MIME type
-==================================================
-
-Some Bugzilla pages have alternate formats, other than just plain
-HTML. In particular, a few Bugzilla pages can
-output their contents as either XUL (a special
-Mozilla format, that looks like a program GUI)
-or RDF (a type of structured XML
-that can be read by various programs).
-
-In order for your users to see these pages correctly, Apache must
-send them with the right MIME type. To do this,
-add the following lines to your Apache configuration, either in the
-``<VirtualHost>`` section for your
-Bugzilla, or in the ``<Directory>``
-section for your Bugzilla:
-
-.. code-block:: apache
-
-    AddType application/vnd.mozilla.xul+xml .xul
-    AddType application/rdf+xml .rdf
-
-.. _multiple-bz-dbs:
-
-Multiple Bugzilla databases with a single installation
-======================================================
-
-The previous instructions referred to a standard installation, with
-one unique Bugzilla database. However, you may want to host several
-distinct installations, without having several copies of the code. This is
-possible by using the PROJECT environment variable. When accessed,
-Bugzilla checks for the existence of this variable, and if present, uses
-its value to check for an alternative configuration file named
-:file:`localconfig.<PROJECT>` in the same location as
-the default one (:file:`localconfig`). It also checks for
-customized templates in a directory named
-:file:`<PROJECT>` in the same location as the
-default one (:file:`template/<langcode>`). By default
-this is :file:`template/en/default` so PROJECT's templates
-would be located at :file:`template/en/PROJECT`.
-
-To set up an alternate installation, just export PROJECT=foo before
-running :command:`checksetup.pl` for the first time. It will
-result in a file called :file:`localconfig.foo` instead of
-:file:`localconfig`. Edit this file as described above, with
-reference to a new database, and re-run :command:`checksetup.pl`
-to populate it. That's all.
-
-Now you have to configure the web server to pass this environment
-variable when accessed via an alternate URL, such as virtual host for
-instance. The following is an example of how you could do it in Apache,
-other Webservers may differ.
-
-.. code-block:: apache
-
-    <VirtualHost 212.85.153.228:80>
-    ServerName foo.bar.baz
-    SetEnv PROJECT foo
-    Alias /bugzilla /var/www/bugzilla
-    </VirtualHost>
-
-Don't forget to also export this variable before accessing Bugzilla
-by other means, such as cron tasks for instance.
-

mozilla/webtools/bugzilla/docs/en/rst/installing/quick-start.rst

@@ -22,8 +22,8 @@ home page. It requires a little familiarity with Linux and the command line.
    Here are some tips:
 
    * Choose any server name you like.
-   * When creating the initial user, call it "bugzilla", give it a strong
+   * When creating the initial Linux user, call it "bugzilla", give it a 
-     password, and write it down.
+     strong password, and write that password down.
    * You do not need an encrypted home directory.
    * Choose all the defaults for the "partitioning" part (excepting of course
      where the default is "No" and you need to press "Yes" to continue).
@@ -31,7 +31,7 @@ home page. It requires a little familiarity with Linux and the command line.
      them manually.
    * From the install options, choose "OpenSSH Server" and "LAMP Server".
    * Set the password for the MySQL root user to a strong password, and write
-     it down.
+     that password down.
    * Install the Grub boot loader to the Master Boot Record.
 
    Reboot when the installer finishes.
@@ -124,9 +124,9 @@ home page. It requires a little familiarity with Linux and the command line.
 8. Check Setup
 
    Bugzilla comes with a :file:`checksetup.pl` script which helps with the
-   installation process. It needs to be run twice. The first time, it
+   installation process. It will need to be run twice. The first time, it
    generates a config file (called :file:`localconfig`) for the database
-   access information, and the second time
+   access information, and the second time (step 10)
    it uses the info you put in the config file to set up the database.
 
    :command:`cd /var/www/html`
@@ -176,14 +176,15 @@ home page. It requires a little familiarity with Linux and the command line.
 
     :command:`lynx http://localhost/`
 
-    Using Bugzilla through Lynx doesn't work for real, but viewing the front
+    It's not really possible to use Bugzilla for real through Lynx, but you
-    page can validate visually that it's up and running.
+    can view the front page to validate visually that it's up and running.
     
     You might well need to configure your DNS such that the server has, and
     is reachable by, a name rather than IP address. Doing so is out of scope
     of this document. In the mean time, it is available on your local network
-    at ``http://<ip address>/``, where ``<ip address>`` is probably the "inet addr"
+    at ``http://<ip address>/``, where ``<ip address>`` is (unless you have
-    value displayed when you run :command:`ifconfig eth0`.
+    a complext network setup) the "inet addr" value displayed when you run
+    :command:`ifconfig eth0`.
 
 13. Configure Bugzilla
 
@@ -199,16 +200,16 @@ home page. It requires a little familiarity with Linux and the command line.
     Click "Save Changes" at the bottom of the page.
 
     There are several ways to get Bugzilla to send email. The easiest is to
-    use Gmail, so we do that here so you have it working. Create a new Gmail
+    use Gmail, so we do that here so you have it working. Visit
-    account for your Bugzilla to use at https://gmail.com. Then, open the "Email"
+    https://gmail.com and create a new Gmail account for your Bugzilla to use.
-    section of the Parameters using the link in the left column, and set the
+    Then, open the "Email" section of the Parameters using the link in the
-    following parameter values:
+    left column, and set the following parameter values:
     
     * mail_delivery_method: SMTP
-    * mailfrom: ``bugzilla_email_address@gmail.com``
+    * mailfrom: ``new_gmail_address@gmail.com``
     * smtpserver: ``smtp.gmail.com:465``
-    * smtp_username: ``bugzilla_email_address@gmail.com``
+    * smtp_username: ``new_gmail_address@gmail.com``
-    * smtp_password: ``the_gmail_password``
+    * smtp_password: ``new_gmail_password``
     * smtp_ssl: On
 
     Click "Save Changes" at the bottom of the page.

mozilla/webtools/bugzilla/docs/en/rst/upgrading/upgrading-from-bazaar.rst

@@ -3,17 +3,17 @@
 Upgrading from Bazaar
 #####################
 
-The procedure to switch to Git is as follows:
+The procedure to switch to Git is as follows. The idea is to switch version
+control systems without changing the exact version of Bugzilla you are using,
+to minimise the risk of conflict or problems. Any major upgrade can then
+happen as a separate step. 
 
-Update Your Bugzilla To The Latest Point Release
+Update Bugzilla To The Latest Point Release
-================================================
+===========================================
 
-The idea is to switch version control systems without changing the exact
+It is recommended that you switch while using the latest
-version of Bugzilla you are using, to minimise the risk of conflict or
+point release for your major version. You can update to the latest point
-problems. Any major upgrade can then happen
+release using bzr.
-as a separate step. It is recommended that you switch while using the latest
-point release for your version. You can update to the latest point release
-using bzr.
 
 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
@@ -75,7 +75,7 @@ into a separate directory alongside your existing Bugzilla installation
 
 You will need a copy of the git program. All Linux installations 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>`_. XXXmake_common
+`download the official build <http://www.git-scm.com/downloads>`_.
 
 Once git is installed, run these commands to pull a copy of Bugzilla:
 
@@ -87,8 +87,8 @@ Once git is installed, run these commands to pull a copy of Bugzilla:
 
 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 X.Y. :file:`bugzilla-git` is the name of the local
+point release of version $VERSION. :file:`bugzilla-git` is the name of the
-directory into which the source code will be downloaded.
+local directory into which the source code will be downloaded.
 
 Shut Down Bugzilla
 ==================
@@ -158,7 +158,7 @@ Now we swap the directories over, and run checksetup.pl to confirm that all
 is well. From the directory containing the :file:`bugzilla` and
 :file:`bugzilla-git` directories, run:
 
-:command:`mv bugzilla bugzilla-bzr`
+:command:`mv bugzilla bugzilla-old`
 
 :command:`mv bugzilla-git bugzilla`
 

mozilla/webtools/bugzilla/docs/en/rst/upgrading/upgrading-from-cvs.rst

@@ -5,8 +5,9 @@ Upgrading from CVS
 
 XXX https://wiki.mozilla.org/Bugzilla:Moving_From_CVS_To_Bazaar
 
-This will be a clone of the Bzr instructions but using CVS commands.
+This will be the same as the Bzr instructions but using CVS commands.
-We might share some text using the include directive
+There are only 3 bzr commands, so we should be able to share the rest of
-if there is a long enough section to be worth splitting it out. But I'm
+the text.
-not going to fill it in until the Bzr instructions have had a review,
+
+I'm not going to fill it in until the Bzr instructions have had a review,
 to save having to maintain two copies of the same stuff.

mozilla/webtools/bugzilla/docs/en/rst/upgrading/upgrading-with-git.rst

@@ -32,6 +32,9 @@ steps to take:
    upgrading to and all intermediate versions, particularly the "Notes for
    Upgraders" sections, if present.
 
+   XXX We need to make these more accessible - they are currently rather hard
+   to find. We could collate them on a single page with no intervening cruft.
+
 #. Run the :ref:`sanity-check` on your installation. Attempt to fix all
    warnings that the page produces before you go any further, or it's
    possible that you may experience problems during your upgrade.
@@ -45,8 +48,8 @@ steps to take:
 
 .. _upgrade-modified:
 
-If you have modified your Bugzilla
+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
@@ -94,8 +97,9 @@ your existing database and settings to the new version.
    .. 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
-      would be a problem for you, you can determine timings by doing a test
+      length of downtime would be a problem for you, you can determine
-      upgrade on a development server with the production data.
+      timings for your particular situation by doing a test upgrade on a
+      development server with the production data.
 
 .. _upgrade-finish: