Merge remote-tracking branch 'upstream/5.0' into bugstest

Signed-off-by: Robin H. Johnson <robbat2@gentoo.org>

8 files changed, 140 insertions, 109 deletions

diff --git a/docs/en/rst/api/core/v1/comment.rst b/docs/en/rst/api/core/v1/comment.rst
index 60fabb93b..946cf79fe 100644
--- a/docs/en/rst/api/core/v1/comment.rst
+++ b/docs/en/rst/api/core/v1/comment.rst
@@ -122,19 +122,14 @@ To create a comment on a current bug.
 .. code-block:: js
 
    {
-     "ids" : [123,..],
      "comment" : "This is an additional comment",
      "is_private" : false
    }
 
-``ids`` is optional in the data example above and can be used to specify adding
-a comment to more than one bug at the same time.
-
 ===========  =======  ===========================================================
 name         type     description
 ===========  =======  ===========================================================
 **id**       int      The ID or alias of the bug to append a comment to.
-ids          array    List of integer bug IDs to add the comment to.
 **comment**  string   The comment to append to the bug. If this is empty
                       or all whitespace, an error will be thrown saying that you
                       did not set the ``comment`` parameter.
diff --git a/docs/en/rst/installing/apache-windows.rst b/docs/en/rst/installing/apache-windows.rst
index 5e8ac8928..fca8ef5eb 100644
--- a/docs/en/rst/installing/apache-windows.rst
+++ b/docs/en/rst/installing/apache-windows.rst
@@ -3,29 +3,54 @@
 Apache
 ######
 
-These instructions require editing the Apache configuration file, which is
-at :file:`C:\\Program Files\\Apache Group\\Apache2\\conf\\httpd.conf`.
+Bugzilla supports all versions of Apache 2.2.x and 2.4.x.
 
 Installing
 ==========
 
-Download the Apache HTTP Server, version 2.2.x or higher, from
-`the Apache website <http://httpd.apache.org/download.cgi>`_.
+Download the Apache HTTP Server as a :file:`.zip` archive either from the
+`Apache Lounge website <http://www.apachelounge.com/download>`_ or from the
+`Apache Haus website <http://www.apachehaus.com/cgi-bin/download.plx>`_.
 
-Apache uses a standard Windows installer. Just follow the prompts, making sure
-you "Install for All Users". Be aware the Apache will always install itself
-into an :file:`Apache2` directory under what ever path you specify. The
-default install path will be displayed as
-:file:`C:\\Program Files\\Apache Group`, which will result in Apache being
-installed to :file:`C:\\Program Files\\Apache Group\\Apache2`.
+Unzip the archive into :file:`C:\\Apache24`. If you move it elsewhere, then
+you must edit several variables in :file:`httpd.conf`, including ``ServerRoot``
+and ``DocumentRoot``.
 
-If you are already running IIS on your machine, you must configure Apache to
-run on a port other than 80, which IIS is using. However you aren't asked the
-port to listen on at install time. Choose "All Users" (which says port 80),
-and we'll change the port later.
+You must now edit the Apache configuration file :file:`C:\\Apache24\\conf\\httpd.conf`
+and do the following steps:
 
-The remainder of this document assumes you have installed Apache into
-the default location, :file:`C:\\Program Files\\Apache Group\\Apache2`.
+#. Uncomment ``LoadModule cgi_module modules/mod_cgi.so`` at the beginning of the
+   file to enable CGI support.
+#. Uncomment ``AddHandler cgi-script .cgi`` to register :file:`.cgi` files
+   as CGI scripts. For this handler to work, you must create a key in the
+   Windows registry named ``HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command`` with
+   the default value pointing to the full path of :file:`perl.exe` with a ``-T``
+   parameter. For example :file:`C:\\Perl\\bin\\perl.exe -T` if you use ActivePerl,
+   or :file:`C:\\Strawberry\\perl\\bin\\perl.exe -T` if you use Strawberry Perl.
+#. Add an Alias and a Directory for Bugzilla:
+
+.. code-block:: apache
+
+    Alias "/bugzilla/" "C:/bugzilla/"
+    <Directory "C:/bugzilla">
+        ScriptInterpreterSource Registry-Strict
+        Options +ExecCGI +FollowSymLinks
+        DirectoryIndex index.cgi index.html
+        AllowOverride All
+        Require all granted
+    </Directory>
+
+.. warning:: The above block takes a simple approach to access control and is
+             correct for Apache 2.4. For Apache 2.2, replace ``Require all granted``
+             with ``Allow from all``. If you have other access control
+             requirements, you may need to make further modifications.
+
+You now save your changes and start Apache as a service. From the Windows
+command line (:file:`cmd.exe`):
+
+:command:`C:\\Apache24\\bin>httpd.exe -k install`
+
+That's it! Bugzilla is now accessible from http://localhost/bugzilla.
 
 Apache Account Permissions
 ==========================
@@ -40,58 +65,12 @@ and modify access to the following directories and all their subdirectories.
 Depending on your version of Windows, this access may already be granted.
 
 * :file:`C:\\Bugzilla\\data`
-* :file:`C:\\Program Files\\Apache Group\\Apache2\\logs`
-* :file:`C:\\Temp`
+* :file:`C:\\Apache24\\logs`
 * :file:`C:\\Windows\\Temp`
 
 Note that :file:`C:\\Bugzilla\\data` is created the first time you run
 :file:`checksetup.pl`.
 
-Port and DocumentRoot
-=====================
-
-Edit the Apache configuration file (see above).
-
-If you need to change the port that Apache runs on (listens on, or binds to),
-for example because another web server such as IIS is running on the same
-machine, edit the ``Listen`` option and change the value after the colon.
-
-Change the ``DocumentRoot`` setting to point to :file:`C:/Bugzilla`. There
-are two locations in :file:`httpd.conf` that need to be updated (search for
-``DocumentRoot``). You need to use ``/`` instead of ``\`` as a path separator.
-
-Enable CGI Support
-==================
-
-Edit the Apache configuration file (see above).
-
-To enable CGI support in Apache, you need to enable the CGI handler, by
-uncommenting the ``AddHandler cgi-script .cgi`` line.
-
-Teach Apache About Bugzilla
-===========================
-
-Edit the Apache configuration file (see above).
-
-Add the following stanza:
-
-.. code-block:: apache
-
-   <Directory "C:/Bugzilla">
-       ScriptInterpreterSource Registry-Strict
-       Options +ExecCGI +FollowSymLinks
-       DirectoryIndex index.cgi index.html
-       AllowOverride Limit FileInfo Indexes Options
-   </Directory>
-
-In order for ``ScriptInterpreterSource Registry-Strict`` to work, you also
-need to add an entry to the Registry so Apache will use Perl to execute .cgi
-files.
-
-Create a key ``HKEY_CLASSES_ROOT\.cgi\Shell\ExecCGI\Command`` with the
-default value of the full path of :file:`perl.exe` with a ``-T`` parameter.
-For example :file:`C:\\Perl\\bin\\perl.exe -T`.
-
 Logging
 =======
 
@@ -118,11 +97,40 @@ in its log files.
 (If you have configured Apache differently, a different log line might apply.
 Adjust these instructions accordingly.)
 
+Using Apache with SSL
+=====================
+
+If you want to enable SSL with Apache, i.e. access Bugzilla from
+https://localhost/bugzilla, you need to do some extra steps:
+
+#. Edit :file:`C:\\Apache24\\conf\\httpd.conf` and uncomment these lines:
+
+   * ``LoadModule ssl_module modules/mod_ssl.so``
+   * ``LoadModule socache_shmcb_module modules/mod_socache_shmcb.so``
+   * ``Include conf/extra/httpd-ssl.conf``
+
+#. Create your :file:`.key` and :file:`.crt` files using :file:`openssl.exe`
+   provided with Apache:
+
+   :command:`C:\\Apache24\\bin>openssl.exe req -x509 -nodes -days 730 -newkey rsa:2048 -keyout server.key -out server.crt`
+
+   :file:`openssl.exe` will ask you a few questions about your location and
+   your company name to populate fields of the certificate.
+
+#. Once the key and the certificate for your server are generated, move them
+   into :file:`C:\\Apache24\\conf` so that their location matches the
+   ``SSLCertificateFile`` and ``SSLCertificateKeyFile`` variables defined in
+   :file:`C:\\Apache24\\conf\\extra\\httpd-ssl.conf` (which you don't need to
+   edit).
+
+.. note:: This process leads to a self-signed certificate which will generate
+         browser warnings on first visit. If your Bugzilla has a public DNS
+         name, you can get a cert from a CA which will not have this problem.
+
 Restart Apache
 ==============
 
-Finally, restart Apache to get it pick up the changes:
-
-:command:`net stop apache2`
+Finally, restart Apache to pick up the changes, either from the Services
+console or from the command line:
 
-:command:`net start apache2`
+:command:`C:\\Apache24\\bin>httpd.exe -k restart`
diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst
index 856512a7f..f98d20df0 100644
--- a/docs/en/rst/installing/apache.rst
+++ b/docs/en/rst/installing/apache.rst
@@ -68,7 +68,7 @@ mod_cgi, do the following:
      AddHandler cgi-script .cgi
      Options +ExecCGI +FollowSymLinks
      DirectoryIndex index.cgi index.html
-     AllowOverride Limit FileInfo Indexes Options
+     AllowOverride All
    </Directory>
 
 These instructions allow Apache to run .cgi files found within the Bugzilla
diff --git a/docs/en/rst/installing/essential-post-install-config.rst b/docs/en/rst/installing/essential-post-install-config.rst
index c5e9c0bc1..1b9fd6b94 100644
--- a/docs/en/rst/installing/essential-post-install-config.rst
+++ b/docs/en/rst/installing/essential-post-install-config.rst
@@ -25,9 +25,9 @@ The first set of these are in the :guilabel:`Required Settings` section.
   this is the SSL URL by which people should access Bugzilla's front page.
 * :param:`ssl_redirect`: Set this if you want everyone to be redirected
   to use the SSL version. Recommended if you have set up SSL.
-* :param:`cookiebase`: Bugzilla uses cookies to remember who each user is.
+* :param:`cookiepath`: Bugzilla uses cookies to remember who each user is.
   In order to set those cookies in the correct scope, you may need to set a
-  cookiebase. If your Bugzilla is at the root of your domain, you don't need
+  cookiepath. If your Bugzilla is at the root of your domain, you don't need
   to change the default value.
 
 You may want to put your email address in the :param:`maintainer`
diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst
index 6a1a7ab53..1670db5f5 100644
--- a/docs/en/rst/installing/iis.rst
+++ b/docs/en/rst/installing/iis.rst
@@ -91,6 +91,29 @@ From the top-level menu, which contains the name of your machine, click
 
 :command:`iisreset`
 
+Enable Rewrite Rules for REST
+=============================
+
+REST URLs are usually of the form http://.../bugzilla/rest/version instead of
+http://.../bugzilla/rest.cgi/version. To let IIS redirect rest/ URLs to rest.cgi,
+you need to download and install the
+`URL Rewrite extension for IIS <http://www.iis.net/downloads/microsoft/url-rewrite>`_.
+Direct download links are available at the bottom of the page for both x86 and
+x64 Windows.
+
+Once installed, you open the IIS Manager again and go to your Bugzilla
+Application. From here, double-click :guilabel:`URL Rewrite`. Then click
+:guilabel:`Add Rule(s)` under the :guilabel:`Actions` menu and click
+:guilabel:`Blank rule` in the :guilabel:`Inbound rules` section.
+
+Fill the fields as follows. Other fields do not need to be edited.
+
+* :guilabel:`Name`: ``REST``
+* :guilabel:`Pattern`: ``^rest/(.*)$``
+* :guilabel:`Rewrite URL`: ``rest.cgi/{R:1}``
+
+There is no need to restart IIS. Changes take effect immediately.
+
 Common Problems
 ===============
 
@@ -104,6 +127,3 @@ Bugzilla runs but it's not possible to log in
 IIS returns HTTP 502 errors
   You probably forgot the ``-T`` argument to :file:`perl` when configuring the
   executable in IIS.
-
-XMLRPC interface not working with IIS
-  This is a known issue. See :bug:`708252`.
diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst
index 0dad2056e..ff4258e6a 100644
--- a/docs/en/rst/installing/linux.rst
+++ b/docs/en/rst/installing/linux.rst
@@ -35,11 +35,9 @@ The following command will install Red Hat's packaged version of Bugzilla:
 
 :command:`yum install bugzilla httpd mysql-server`
 
-However, if you go this route, you need to read :bug:`415605`, which details
-some problems with the Email::Send package. Then, you can skip to
-:ref:`configuring your database <linux-config-database>`. It may be useful to
-know that Fedora stores the Bugzilla files in :file:`/usr/share/bugzilla`, so
-that's where you'll run :file:`checksetup.pl`.
+Then, you can skip to :ref:`configuring your database <linux-config-database>`.
+It may be useful to know that Fedora stores the Bugzilla files in
+:file:`/usr/share/bugzilla`, so that's where you'll run :file:`checksetup.pl`.
 
 If you want to install a version of Bugzilla from the Bugzilla project, you
 will instead need:
diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst
index c9c7b2d26..c2da8da23 100644
--- a/docs/en/rst/installing/quick-start.rst
+++ b/docs/en/rst/installing/quick-start.rst
@@ -117,7 +117,7 @@ Paste in the following and save:
    AddHandler cgi-script .cgi
    Options +ExecCGI
    DirectoryIndex index.cgi index.html
-   AllowOverride Limit FileInfo Indexes Options
+   AllowOverride All
  </Directory>
 
 :command:`a2ensite bugzilla`
diff --git a/docs/en/rst/installing/windows.rst b/docs/en/rst/installing/windows.rst
index bf33ca330..ef1a1f6f4 100644
--- a/docs/en/rst/installing/windows.rst
+++ b/docs/en/rst/installing/windows.rst
@@ -3,28 +3,34 @@
 Windows
 #######
 
-Making Bugzilla work on Windows is more difficult than making it work on Unix,
-fewer Bugzilla developers use it and so it's less well supported. We would
-particularly recommend against doing it for a large site. However, if
-you are still determined to go ahead, here's how.
+Making Bugzilla work on Windows is not more difficult than making it work on
+Linux. However, fewer developers use Windows to test Bugzilla and so we would
+still recommend using Linux for large sites to get better support.
 
 .. windows-install-perl:
 
-ActiveState Perl
-================
+Perl
+====
 
-ActiveState make a popular distribution of Perl for Windows.
+You have two main choices to install Perl on Windows: ActivePerl and Strawberry
+Perl.
 
-Download the ActiveState Perl 5.12.4 or higher MSI installer from the
+The ActivePerl Windows Installer can be downloaded from the
 `ActiveState website <http://www.activestate.com/activeperl/downloads>`_.
-
-ActiveState Perl uses a standard Windows Installer. Install, sticking with
-the defaults, which will install Perl into :file:`C:\\Perl`. It is not
+Perl will be installed by default into :file:`C:\\Perl`. It is not
 recommended to install Perl into a directory containing a space, such as
-:file:`C:\\Program Files`.
+:file:`C:\\Program Files`. Once the install has completed, log out and log in
+again to pick up the changes to the ``PATH`` environment variable.
+
+The Strawberry Perl Windows Installer can be downloaded from the
+`Strawberry Perl website <http://strawberryperl.com>`_. Perl will be installed
+by default into :file:`C:\\Strawberry`.
 
-Once the install has completed, log out and log in again to pick up the
-changes to the ``PATH`` environment variable.
+One big advantage of Strawberry Perl over ActivePerl is that with Strawberry
+Perl, you can use the usual tools available on other OSes to install missing
+Perl modules directly from CPAN, whereas ActivePerl requires you to use its own
+:file:`ppm` tool to download pre-compiled Perl modules from ActiveState.
+The modules in the ActivePerl repository may be a bit older than those on CPAN.
 
 .. _windows-install-bzfiles:
 
@@ -37,7 +43,7 @@ git from the `git website <http://git-scm.com/download>`_, and then run:
 :command:`git clone --branch release-X.X-stable https://git.mozilla.org/bugzilla/bugzilla C:\\bugzilla`
 
 where "X.X" is the 2-digit version number of the stable release of Bugzilla
-that you want (e.g. 4.4).
+that you want (e.g. 5.0).
 
 The rest of this documentation assumes you have installed Bugzilla into
 :file:`C:\\bugzilla`. Adjust paths appropriately if not.
@@ -53,16 +59,17 @@ which any competent Windows archiving tool should be able to open.
 Perl Modules
 ============
 
-Bugzilla requires a number of perl modules to be installed. They are
-available in the ActiveState repository, and are installed with the
-:file:`ppm` tool. You can either use it on the command line, as below,
-or just type :command:`ppm`, and you will get a GUI.
+Bugzilla requires a number of Perl modules to be installed. Some of them are
+mandatory, and some others, which enable additional features, are optional.
 
+If you are using ActivePerl, these modules are available in the ActiveState
+repository, and are installed with the :file:`ppm` tool. You can either use it
+on the command line as below, or just type :command:`ppm`, and you will get a GUI.
 If you use a proxy server or a firewall you may have trouble running PPM.
 This is covered in the
 `ActivePerl FAQ <http://aspn.activestate.com/ASPN/docs/ActivePerl/faq/ActivePerl-faq2.html#ppm_and_proxies>`_.
 
-Install the following modules with:
+Install the following mandatory modules with:
 
 :command:`ppm install <modulename>`
 
@@ -120,12 +127,15 @@ installed:
 * File-Copy-Recursive
 * GraphViz
 
-.. warning:: These lists have been extracted from Bugzilla's source code and
-             have not been tested. Please let us know if you find errors in it
-             of any sort.
+If you are using Strawberry Perl, you should use the :file:`install-module.pl`
+script to install modules, which is the same script used for Linux. Some of
+the required modules are already installed by default. The remaining ones can
+be installed using the command:
+
+:command:`perl install-module.pl <modulename>`
 
-.. note:: The :file:`install-module.pl` script doesn't work with ActivePerl
-   on Windows.
+The list of modules to install will be displayed by :file:`checksetup.pl`; see
+below.
 
 .. _windows-config-webserver: