WIP; also merge from trunk up to and including bug 1066184.

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

mozilla/webtools/bugzilla/.bzrrev

@@ -1 +1 @@
-9238
+9239

mozilla/webtools/bugzilla/.gitrev

@@ -1 +1 @@
-1d769a4744586b2a0125338aceece84733a6e5e3
+a0646ff7d1452e86361aec4e463f0d9ec2135bfe

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

@@ -23,10 +23,14 @@ A sample of code is illustrated like this:
     Second Line of Code
     ...
 
-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
+This documentation is maintained in
+`reStructured Text
+<http://docutils.sourceforge.net/docs/user/rst/quickstart.html>`_ format using
+the `Sphinx <http://www.sphinx-doc.org/>`_ documentation system. It has
+recently been rewritten, so undoubtedly has bugs. Please file bugs on it in
+the `Bugzilla Documentation
 <https://bugzilla.mozilla.org/enter_bug.cgi?product=Bugzilla;component=Documentation>`_
-component. There is a :ref:`Style Guide <style-guide>` to help you.
+component. If you want to make a patch, that would be wonderful. Changes are
+best submitted as diffs, attached to a bug. There is a
+:ref:`Style Guide <style-guide>` to help you write any new text and markup.
 

mozilla/webtools/bugzilla/docs/en/rst/administering/parameters.rst

@@ -472,7 +472,7 @@ user_verify_class (in the Authentication section)
     well, you may otherwise not be able to log back in to Bugzilla once
     you log out.
     If this happens to you, you will need to manually edit
-    :file:`data/params` and set :param:`user_verify_class` to
+    :file:`data/params.json` and set :param:`user_verify_class` to
     :paramval:`DB`.
 
 LDAPserver
@@ -548,7 +548,7 @@ user_verify_class (in the Authentication section)
     well, you may otherwise not be able to log back in to Bugzilla once
     you log out.
     If this happens to you, you will need to manually edit
-    :file:`data/params` and set :param:`user_verify_class` to
+    :file:`data/params.json` and set :param:`user_verify_class` to
     :paramval:`DB`.
 
 RADIUS_server

mozilla/webtools/bugzilla/docs/en/rst/conf.py

@@ -158,7 +158,7 @@ html_use_smartypants = False
 #html_domain_indices = True
 
 # If false, no index is generated.
-#html_use_index = True
+html_use_index = False
 
 # If true, the index is split into individual pages for each letter.
 #html_split_index = False

mozilla/webtools/bugzilla/docs/en/rst/customizing/extensions.rst

@@ -11,5 +11,6 @@ effort.
 
 We maintain a
 `list of available extensions <https://wiki.mozilla.org/Bugzilla:Addons>`_
-on our wiki. You would need to
+written by other people on our wiki. You would need to
 make sure that the extension in question works with your version of Bugzilla.
+Or you can look into :ref:`writing your own extension <writing-extensions>`.

mozilla/webtools/bugzilla/docs/en/rst/customizing/languages.rst

@@ -1,7 +1,8 @@
 Languages
 =========
 
-Bugzilla's templates can be localized, although it's a big job. If you have
+Bugzilla's templates can be localized, although it's a `big job
+<https://wiki.mozilla.org/Bugzilla:L10n:Guide>`_. If you have
 a localized set of templates for your version of Bugzilla, Bugzilla can 
 support multiple languages at once. In that case, Bugzilla honours the user's
 ``Accept-Language`` HTTP header when deciding which language to serve.
@@ -9,4 +10,7 @@ support multiple languages at once. In that case, Bugzilla honours the user's
 Many language templates can be obtained from
 `the localization section of the Bugzilla website
 <http://www.bugzilla.org/download.html#localizations>`_. Instructions
-for submitting new languages are also available from that location.
+for submitting new languages are also available from that location. There's
+also a `list of localization teams
+<https://wiki.mozilla.org/Bugzilla:L10n:Localization_Teams>`_; you might
+want to contact someone to ask about the status of their localization.

mozilla/webtools/bugzilla/docs/en/rst/customizing/templates.rst

@@ -35,38 +35,51 @@ Choosing a Customization Method
 ===============================
 
 If you want to edit Bugzilla's templates, the first decision
-you must make is how you want to go about doing so. There are two
+you must make is how you want to go about doing so. There are three
 choices, and which you use depends mainly on the scope of your
 modifications, and the method you plan to use to upgrade Bugzilla.
 
-The first method of making customizations is to directly edit the
-templates found in :file:`template/en/default`.
-This is probably the best way for minor changes, because when you upgrade
-Bugzilla, either the source code management system or the :file:`patch` tool
-will merge your changes into the new version for you.
+#. You can directly edit the templates found in :file:`template/en/default`.
+   This is probably the best way for minor changes, because when you upgrade
+   Bugzilla, either the source code management system or the :file:`patch` tool
+   will merge your changes into the new version for you.
 
-On the downside, if the merge fails then Bugzilla will not work properly until
-you have fixed the problem and re-integrated your code.
+   On the downside, if the merge fails then Bugzilla will not work properly until
+   you have fixed the problem and re-integrated your code.
 
-The second method is to copy the templates to be modified
-into a mirrored directory structure under
-:file:`template/en/custom`. Templates in this
-directory structure automatically override any identically-named
-and identically-located templates in the
-:file:`template/en/default` directory. (The :file:`custom` directory does not
-exist by default and must be created if you want to use it.)
+#. You can copy the templates to be modified into a mirrored directory
+   structure under :file:`template/en/custom`. Templates in this
+   directory structure automatically override any identically-named
+   and identically-located templates in the
+   :file:`template/en/default` directory. (The :file:`custom` directory does
+   not exist by default and must be created if you want to use it.)
 
-The second method of customization should be used if you are going to make
-major changes, because it is guaranteed that the contents of this directory
-will not be touched during an upgrade, and you can then decide whether
+#. You can use the hooks built into many of the templates to add or modify
+   the UI from an :ref:`extension`. Hooks generally don't go away and have
+   a stable interface. 
+
+The third method is the best if there are hooks in the appropriate places.
+Unlike code hooks, there is no requirement to document template hooks, so
+you just have to open up the template and see (search for 'Hook.process').
+
+If there are no hooks available, then the second method of customization
+should be used if you are going to make major changes, because it is
+guaranteed that the contents of the :file:`custom` directory will not be
+touched during an upgrade, and you can then decide whether
 to continue using your own templates, or make the effort to merge your
-changes into the new versions by hand.
+changes into the new versions by hand. It's also good for entirely new files,
+and for a few files like :file:`bug/create/user-message.html.tmpl` which
+are designed to be entirely replaced.
 
-Using this method, your installation may break if incompatible
-changes are made to the template interface.  Such changes should
+Using the second method, your installation may break if incompatible
+changes are made to the template interface. Such changes should
 be documented in the release notes, provided you are using a
 stable release of Bugzilla, so you should be able to see them coming.
 
+For minor changes, the convenience of the first method is hard to beat. You
+can see what you've changed using :command:`git diff`, which you can't if
+you fork the file into the :file:`custom` directory.
+
 .. _template-edit:
 
 How To Edit Templates
@@ -77,8 +90,6 @@ How To Edit Templates
    sections of the
    `Developers' Guide <http://www.bugzilla.org/docs/developer.html>`_.
 
-   XXX Is this still there?
-
 Bugzilla uses a templating system called Template Toolkit. The syntax of the
 TT language is beyond the scope of
 this guide. It's reasonably easy to pick up by looking at the current
@@ -146,7 +157,7 @@ constant. If your content type is not there, add it. Remember
 the three- or four-letter tag assigned to your content type.
 This tag will be part of the template filename.
 
-.. note:: After adding or changing a content type, it's suitable to
+.. note:: After adding or changing a content type, you need to
    edit :file:`Bugzilla/Constants.pm` in order to reflect
    the changes. Also, the file should be kept up to date after an
    upgrade if content types have been customized in the past.

mozilla/webtools/bugzilla/docs/en/rst/customizing/writing-extensions.rst

@@ -4,7 +4,107 @@ Writing Extensions
 ##################
 
 See the `Bugzilla Extension
-documentation <../html/api/Bugzilla/Extension.html>`_ for information on how
-to write an Extension.
+documentation <../html/api/Bugzilla/Extension.html>`_ for the core
+documentation on how to write an Extension. We also have some additional
+tips and tricks here.
 
-XXX Also https://wiki.mozilla.org/Bugzilla:Extension_Notes
+XXX These came from the wiki. Should they actually be integrated into the
+POD, or should some of the POD come here, or something else?
+
+Checking Syntax
+===============
+
+It's not immediately obvious how to check the syntax of your extension's
+modules. Running checksetup.pl might do some of it, but the errors aren't
+necessarily massively informative.
+
+:command:`perl -Mlib=lib -MBugzilla -e 'BEGIN { Bugzilla->extensions; } use Bugzilla::Extension::ExtensionName::Class;'`
+
+(run from ``$BUGZILLA_HOME``) will do the trick.
+
+Adding New Fields To Bugs
+=========================
+
+To add new fields to a bug, you need to do the following:
+
+* Add an ``install_update_db`` hook to add the fields by calling
+  ``Bugzilla::Field->create`` (only if the field doesn't already exist).
+  Here's what it might look like for a single field:
+
+  .. code-block:: perl
+
+    my $field = new Bugzilla::Field({ name => $name });
+    return if $field;
+ 
+    $field = Bugzilla::Field->create({
+        name        => $name,
+        description => $description,
+        type        => $type,        # From list in Constants.pm
+        enter_bug   => 0,
+        buglist     => 0,
+        custom      => 1,
+    });
+
+* Push the name of the field onto the relevant arrays in the ``bug_columns``
+  and ``bug_fields`` hooks.
+
+* If you want direct accessors, or other functions on the object, you need to
+  add a BEGIN block to your Extension.pm:
+
+  .. code-block:: perl
+
+    BEGIN { 
+       *Bugzilla::Bug::is_foopy = \&_bug_is_foopy; 
+    }
+ 
+    ...
+ 
+    sub _bug_is_foopy {
+        return $_[0]->{'is_foopy'};
+    }
+
+* You don't have to change ``Bugzilla/DB/Schema.pm``.
+
+Adding New Fields To Other Things
+=================================
+
+If you are adding the new fields to an object other than a bug, you need to
+go a bit lower-level. 
+
+* In ``install_update_db``, use ``bz_add_column`` instead
+
+* Push on the columns in ``object_columns`` and ``object_update_columns``
+  instead of ``bug_columns``.
+
+* Add validators for the values in ``object_validators``
+
+The process for adding accessor functions is the same.
+
+Adding Configuration Panels
+===========================
+
+As well as using the ``config_add_panels`` hook, you will need a template to
+define the UI strings for the panel. See the templates in
+:file:`template/en/default/admin/params` for examples, and put your own
+template in :file:`template/en/default/admin/params` in your extension's
+directory.
+
+Adding User Preferences
+=======================
+
+To add a new user preference:
+
+* Call ``add_setting('setting_name', ['some_option', 'another_option'],
+  'some_option')`` in the ``install_before_final_checks`` hook. (The last
+  parameter is the name of the option which should be the default.)
+
+* Add descriptions for the identifiers for your setting and choices
+  (setting_name, some_option etc.) to the hash defined in
+  :file:`global/setting-descs.none.tmpl`. Do this in a hook:
+  :file:`hook/global/setting-descs-settings.none.tmpl`. Your code can see the
+  hash variable; just set more members in it.
+
+* To change behaviour based on the setting, reference it in templates using
+  ``[% user.settings.setting_name.value %]``. Reference it in code using
+  ``$user->settings->{'setting_name'}->{'value'}``. The value will be one of
+  the option tag names (e.g. some_option).

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

@@ -8,6 +8,33 @@ 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.
 
+These instructions require editing the Apache configuration file.
+In Fedora and Red Hat Linux, this file is found as
+:file:`/etc/httpd/conf/httpd.conf`.
+In Ubuntu and Debian, it is :file:`/etc/apache2/apache2.conf`.
+
+Securing Apache
+===============
+
+When external systems interact with Bugzilla via webservices
+(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL
+(query-string). Therefore, to avoid storing passwords in clear text on the
+server we recommend configuring Apache to not include the query-string in its
+log files.
+
+#. Edit the Apache configuration file (see above).
+
+#. Find the following line in the above mentioned file, which defines the
+   logging format for ``vhost_combined``:
+
+   .. code-block:: apache
+
+      LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined
+
+#. Replace ``%r`` with ``%m %U``.
+
+#. Restart Apache.
+
 .. _apache-mod_cgi:
 
 Apache with mod_cgi
@@ -18,9 +45,7 @@ mod_cgi, do the following:
 
 XXX Shouldn't we be using sites-available/sites-enabled here?
 
-#. Load :file:`httpd.conf` in your editor.
-   In Fedora and Red Hat Linux, this file is found in
-   :file:`/etc/httpd/conf`.
+#. Edit the Apache configuration file (see above).
 
 #. Apache uses ``<Directory>``
    directives to permit fine-grained permission setting. Add the

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

@@ -64,3 +64,5 @@ Also, and this can't be stressed enough, make sure that files
 such as :file:`localconfig` and your
 :file:`data` directory are
 secured as described in :ref:`security-webserver-access`.
+
+XXX See also https://wiki.mozilla.org/Installing_under_IIS_7.5

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

@@ -25,9 +25,43 @@ Install Packages
 Use your distribution's package manager to install Perl, your preferred
 database engine (MySQL if in doubt), and a webserver (Apache if in doubt).
 
-XXX Package lists for specific distros
+The commands below will install those things and some of Bugzilla's other
+prerequisites as well. If you find a package doesn't install or the name
+is not found, just remove it from the list and reissue the command.
 
-.. _install-perl:
+Fedora and Red Hat
+------------------
+
+:command:`yum install httpd mysql-server mod_perl mod_perl-devel httpd-devel
+graphviz patchutils gcc perl-DateTime perl-Template-Toolkit perl-Email-Send
+perl-Email-MIME perl-GD perl-Chart perl-Template-GD perl-GDGraph
+perl-GDTextUtil perl-PatchReader perl-MIME-tools perl-LDAP perl-Authen-SASL
+perl-RadiusPerl perl-SOAP-Lite perl-JSON-RPC perl-JSON-XS perl-Test-Taint
+perl-HTML-Scrubber perl-Email-MIME-Attachment-Stripper perl-Email-Reply
+perl-TheSchwartz perl-Daemon-Generic perl-Math-Random-Secure perl-YAML
+perl-Class-Inspector`
+
+If you are running RHEL6, you will have to enable the "RHEL Server Optional"
+channel in RHN to get some of those packages. 
+
+Ubuntu and Debian
+-----------------
+
+:command:`apt-get install git nano`
+
+:command:`apt-get install apache2 mysql-server libappconfig-perl
+libdate-calc-perl libtemplate-perl libmime-perl build-essential
+libdatetime-timezone-perl libdatetime-perl libemail-send-perl
+libemail-mime-perl libemail-mime-modifier-perl libdbi-perl libdbd-mysql-perl
+libcgi-pm-perl libmath-random-isaac-perl libmath-random-isaac-xs-perl
+apache2-mpm-prefork libapache2-mod-perl2 libapache2-mod-perl2-dev
+libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl
+libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl
+libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl
+libtest-taint-perl libauthen-radius-perl libfile-slurp-perl
+libencode-detect-perl libmodule-build-perl libnet-ldap-perl
+libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl
+libhtml-formattext-withlinks-perl libgd-dev lynx-cur`
 
 Perl
 ====

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

@@ -38,8 +38,8 @@ things should still work.
    appropriate variables in :file:`localconfig`.
 
 6. If the new URL to your new Bugzilla installation is different from the old
-   one, update the :param:`urlbase` parameter in :file:`data/params` using
-   a text editor.
+   one, update the :param:`urlbase` parameter in :file:`data/params.json`
+   using a text editor.
 
 7. Copy the database backup file :file:`bugzilla-backup.sql` file from your
    old server to the new one.

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

@@ -10,8 +10,10 @@ The Bugzilla documentation uses
 `reStructured Text (reST) <http://docutils.sourceforge.net/rst.html>`_,
 as extended by our documentation compilation tool,
 `Sphinx <http://sphinx-doc.org/>`_. This document is a reST document for
-demonstration purposes. When you build the docs, it gets built (at least in
-the HTML version) as a standalone file, although it isn't as readable in that
+demonstration purposes. To learn from it, you need to read it in reST form.
+
+When you build the docs, this document gets built (at least in
+the HTML version) as a standalone file, although it isn't as useful in that
 form because some of the directives discussed are invisible or change when
 rendered.
 
@@ -74,14 +76,18 @@ this:
 
 .. code-block:: perl
 
-  # This is some Perl code
-  print "Hello";
+   # This is some Perl code
+   print "Hello";
 
 There is a
 `list of all available lexer names <http://pygments.org/docs/lexers/>`_
 available. We currently use ``console``, ``perl``, and ``sql``. ``none`` is
 also a valid value.
 
+Use 4-space indentation, except where a different value is better so that
+things line up. So normally two spaces for bulleted lists, and 3 spaces
+for .. blocks.
+
 Inline Directives
 #################
 

mozilla/webtools/bugzilla/docs/en/rst/upgrading/overview.rst

@@ -6,6 +6,13 @@ 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.
+
+.. warning:: Upgrading is a one-way process. You cannot "downgrade" an
+   upgraded Bugzilla. If you wish to revert to the old Bugzilla
+   version for any reason, you will have to restore your system
+   from a backup. Those with critical data or large installations may wish
+   to trial 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
@@ -39,6 +46,3 @@ following subdirectories in your root Bugzilla directory:
 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 :ref:`back up <backups>`
-both your Bugzilla directory and your database.

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

@@ -6,9 +6,8 @@ happen as a separate step.
 Update Bugzilla To The Latest Point Release
 ===========================================
 
-It is recommended that you switch while using the latest
-point release for your major version. You can update to the latest point
-release using bzr.
+It is recommended that you switch to Git while using the latest
+point release for your major 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
@@ -25,10 +24,6 @@ is a list of the final point releases:
 * 3.4.14
 * 3.2.10
 * 3.0.11
-
-XXX Do we need below here? Are these versions in bzr? Will anyone be running
-them from a bzr install?
-
 * 2.22.7
 * 2.20.7
 * 2.18.6
@@ -57,7 +52,7 @@ 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 installations have it;
+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>`_.
 

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

@@ -9,7 +9,7 @@ If you have made customizations to your Bugzilla, and you made them by
 changing the Bugzilla code itself (rather than using the Extension system),
 then :file:`patch.diff` will have non-zero size. You will want to keep a copy
 of those changes by keeping a copy of this file. If the file has zero size,
-you haven't made any local customizations.
+you haven't made any local customizations of this sort.
 
 Shut Down Bugzilla
 ==================
@@ -33,13 +33,12 @@ of Bugzilla into the corresponding directory in :file:`bugzilla-new/`:
 
   lib/
   data/
+  template/en/custom (may or may not exist)
 
-You also need to copy an extensions you have written or installed, which are
-in the :file:`extensions/` directory.
+You also need to copy any extensions you have written or installed, which are
+in the :file:`extensions/` directory. |extstatusinfo|
 
-|extstatusinfo|
-
-Then, copy the following file from your current installation of Bugzilla
+Lastly, copy the following file from your current installation of Bugzilla
 into the corresponding place in :file:`bugzilla-new/`:
 
 .. code-block:: none

mozilla/webtools/bugzilla/docs/en/rst/upgrading/upgrading-with-a-tarball.rst

@@ -3,9 +3,9 @@
 Upgrading with a Tarball
 ########################
 
-If you are unable (or unwilling) to use Git, another option that's
-always available is to obtain a tarball of the latest version from our
-website and upgrade your Bugzilla installation from that.
+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
 =================

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

@@ -9,16 +9,6 @@ intermediate steps. There is a script named :file:`checksetup.pl` included
 with Bugzilla that will automatically do all of the database migration
 for you.
 
-.. warning:: Upgrading is a one-way process. You cannot "downgrade" an
-   upgraded Bugzilla. If you wish to revert to the old Bugzilla
-   version for any reason, you will have to restore your database
-   from a backup. Those with critical data or large installations may wish
-   to trial the upgrade on a development server first, using a copy of the
-   production data and configuration.
-
-In the commands below, ``$BUGZILLA_HOME`` represents the directory
-in which Bugzilla is installed.
-
 .. _upgrade-before:
 
 Before You Upgrade
@@ -30,21 +20,18 @@ 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.
+   Upgraders" sections, if present. They may make you aware of additional
+   considerations.
 
    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
+   warnings that the page produces before you start, or it's
    possible that you may experience problems during your upgrade.
 
-#. Shut down your Bugzilla installation by putting some explanatory text
-   in the :param:`shutdownhtml` parameter.
-
-#. Make all necessary :ref:`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.
+#. Work out how to :ref:`back up <backups>` your Bugzilla entirely, and
+   how to restore from a backup if need be.
 
 .. _upgrade-modified:
 
@@ -67,20 +54,37 @@ 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.
 
-XXX Need more here
+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.
+
+Starting the Upgrade
+====================
+
+When you are ready to go:
+
+#. Shut down your Bugzilla installation by putting some explanatory text
+   in the :param:`shutdownhtml` parameter.
+
+#. Make all necessary :ref:`backups`.
+   *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:
 
 Getting The New Bugzilla
 ========================
 
+In the commands below, ``$BUGZILLA_HOME`` represents the directory
+in which Bugzilla is installed.
+
 :command:`cd $BUGZILLA_HOME`
 
 :command:`git checkout`
 
 :command:`git pull`
 
-XXX How to pull latest stable?
+XXX What is the best way to pull latest stable?
 
 .. _upgrade-database:
 
@@ -109,7 +113,7 @@ Finishing The Upgrade
 #. Reactivate Bugzilla by clear the text that you put into the
    :param:`shutdownhtml` parameter.
 
-#. Run a :ref:`sanity-check` on your
+#. 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
-   will not work entirely correctly. 
+   may not work entirely correctly. 

mozilla/webtools/bugzilla/docs/en/rst/using/filing.rst

@@ -23,14 +23,14 @@ for the bug that bit you.
 
 The procedure for filing a bug is as follows:
 
-#. Click the ``New`` link available in the header or footer
-   of pages, or the ``File a Bug`` link on the home page.
+#. Click the :guilabel:`New` link available in the header or footer
+   of pages, or the :guilabel:`File a Bug` link on the home page.
 
 #. First, you have to select the product in which you found a bug.
 
 #. You now see a form where you can specify the component (part of
    the product which is affected by the bug you discovered; if you have
-   no idea, just select ``General`` if such a component exists),
+   no idea, just select :guilabel:`General` if such a component exists),
    the version of the program you were using, the operating system and
    platform your program is running on and the severity of the bug (if the
    bug you found crashes the program, it's probably a major or a critical
@@ -38,7 +38,7 @@ The procedure for filing a bug is as follows:
    something you would like to see implemented, then that's an enhancement).
 
 #. You also need to provide a short but descriptive summary of the bug you found.
-   ``My program is crashing all the time`` is a very poor summary
+   "My program is crashing all the time" is a very poor summary
    and doesn't help developers at all. Try something more meaningful or
    your bug will probably be ignored due to a lack of precision.
    In the Description, give a detailed list of steps to reproduce
@@ -67,7 +67,7 @@ The procedure for filing a bug is as follows:
    should know in order to reproduce the problem, and make sure your
    description of the problem is explicit and clear enough.
    When you think your bug report is ready to go, the last step is to
-   click the ``Submit Bug`` button to add your report into the database.
+   click the :guilabel:`Submit Bug` button to add your report into the database.
 
 .. _cloning-a-bug:
 
@@ -77,7 +77,7 @@ Clone an Existing Bug
 Bugzilla allows you to 'clone' an existing bug. The newly created bug will
 inherit most settings from the old bug. This allows you to track similar
 concerns which require different handling in a new bug. To use this, go to
-the bug that you want to clone, then click the ``Clone This Bug``
-link on the bug page. This will take you to the ``Enter Bug``
+the bug that you want to clone, then click the :guilabel:`Clone This Bug`
+link on the bug page. This will take you to the :guilabel:`Enter Bug`
 page that is filled with the values that the old bug has.
 You can then change the values and/or text if needed.

mozilla/webtools/bugzilla/docs/en/rst/using/preferences.rst

@@ -123,9 +123,20 @@ confirm the change. This helps to prevent account hijacking.
 API Keys
 ========
 
-API Keys allow you to give a "token" to a web service so it can log in to
-Bugzilla as you without knowing your password. You can then revoke that token
-if you stop using the web service.
+API Keys allow you to give a "token" to some external software so it can log
+in to the WebService API as you without knowing your password. You can then
+revoke that token if you stop using the web service, and you don't need to
+change your password everywhere.
+
+You can create more than one API key if required. Each API key has an optional
+description which can help you record what each key is used for.
+
+On this page, you can unrevoke, revoke and change the description of existing
+API keys for your login. A revoked key means that it cannot be used. The
+description for purely for your information, and is optional.
+
+You can also create a new API key by selecting the check box under the 'New
+API key' section of the page.
 
 .. _permissions:
 

mozilla/webtools/bugzilla/docs/en/rst/using/tips.rst

@@ -19,8 +19,12 @@ Other strings which get linkified in the obvious manner are:
 
 + bug 12345
 
++ bugs 123, 456, 789
+
 + comment 7
 
++ comments 1, 2, 3, 4
+
 + bug 23456, comment 53
 
 + attachment 4321
@@ -59,3 +63,29 @@ If you feel a bug you filed was incorrectly marked as a
 DUPLICATE of another, please question it in your bug, not
 the bug it was duped to. Feel free to CC the person who duped it
 if they are not already CCed.
+
+.. _markdown:
+
+Markdown
+--------
+
+Markdown is a structured plain-text format which lets you write comments that
+have more styling than plain text. For example, you may use Markdown for
+making a part of your comment look italic or bold in the generated HTML.
+Bugzilla supports most of the structures defined by
+`standard Markdown <http://daringfireball.net/projects/markdown/basics>`_,
+but does NOT support inline images and inline HTML.
+
+Additionally, three Github Flavored Markdown features are supported.
+
+* `Multiple underscores in words <https://help.github.com/articles/github-flavored-markdown#multiple-underscores-in-words>`_
+
+* `strikethrough <https://help.github.com/articles/github-flavored-markdown#strikethrough>`_
+
+* `fenced code blocks <https://help.github.com/articles/github-flavored-markdown#fenced-code-blocks>`_
+
+To use the Markdown feature, make sure that :guilabel:`Enable Markdown
+support for comments` is set to :guilabel:`on`
+in your :ref:`user-preferences` and that you also check the :guilabel:`Use
+Markdown for this comment` option below the comment box when you want to
+submit a new comment which uses Markdown.