From: Gervase Markham Date: Sun, 14 Sep 2014 15:43:32 +0000 (+0100) Subject: Continued WIP X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=715ec3d7af9693f40aa578391900b093c8c078bb;p=thirdparty%2Fbugzilla.git Continued WIP --- diff --git a/docs/en/rst/about/credits.rst b/docs/en/rst/about/credits.rst index cce2713003..c3954550f3 100644 --- a/docs/en/rst/about/credits.rst +++ b/docs/en/rst/about/credits.rst @@ -3,44 +3,25 @@ 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. +The people listed below have made significant contributions to the +creation of this documentation: + +Andrew Pearson, +Ben FrantzDale, +Dave Lawrence, +Dave Miller, +Dawn Endico, +Eric Hanson, +Gervase Markham, +Jacob Steenhagen, +Joe Robins, +Kevin Brannen, +Martin Wulffeld, +Matthew P. Barnson, +Ron Teitelbaum, +Shane Travis, +Spencer Smith, +Tara Hernandez, +Terry Weissman, +Vlad Dascalu, +Zach Lipton. diff --git a/docs/en/rst/about/document-conventions.rst b/docs/en/rst/about/document-conventions.rst index 7e446bc691..8376f01011 100644 --- a/docs/en/rst/about/document-conventions.rst +++ b/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 `_ documentation system. Changes are best submitted as diffs, attached to a bug filed in the `Bugzilla Documentation `_ component. diff --git a/docs/en/rst/about/introduction.rst b/docs/en/rst/about/introduction.rst index 091472c77d..9beb1775be 100644 --- a/docs/en/rst/about/introduction.rst +++ b/docs/en/rst/about/introduction.rst @@ -3,11 +3,10 @@ Introduction ############ -This is the documentation for version |version| of Bugzilla, a -bug-tracking system from mozilla.org. -Bugzilla is an enterprise-class piece of software -that tracks millions of bugs and issues for hundreds of -organizations around the world. +This is the documentation for version |version| of Bugzilla, a bug-tracking +system from Mozilla. Bugzilla is an enterprise-class piece of software +that tracks millions of bugs and issues for thousands of organizations around +the world. The most current version of this document can always be found on the `Bugzilla Documentation Page `_. diff --git a/docs/en/rst/installing.rst b/docs/en/rst/installing.rst index c59f6e7206..bed9105eb0 100644 --- a/docs/en/rst/installing.rst +++ b/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 `. .. 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/optional-features + installing/post-install-config installing/migrating installing/moving diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst index bc924f0522..6261b46636 100644 --- a/docs/en/rst/installing/apache.rst +++ b/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 `. + 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,18 +70,20 @@ and mod_perl. #. Add the following information to your httpd.conf file, substituting where appropriate with your own local paths. + .. code-block:: apache + + PerlSwitches -w -T + PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl + .. note:: This should be used instead of the 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. + 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 - .. code-block:: apache - - PerlSwitches -w -T - PerlConfigRequire /var/www/html/bugzilla/mod_perl.pl + 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 diff --git a/docs/en/rst/installing/email.rst b/docs/en/rst/installing/email.rst index ac9cc4e4ce..57f662baf5 100644 --- a/docs/en/rst/installing/email.rst +++ b/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 +======================= + +This section corresponds to choosing a :guilabel:`mail_delivery_method` of +``SMTP``. + +This method passes the email off to an existing mail server. Your +organization may well already have one running for their internal email, and +may prefer to use it for confidentiality reasons. If so, you need the +following information about it: + +* The domain name of the server (Parameter: :guilabel:`smtpserver`) +* The username and password to use (Parameters: :guilabel:`smtp_username` and + :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``. -Bugzilla is dependent on the availability of an e-mail system for its -user authentication and for other tasks. +XXX Do we still need this? Why would anyone want to do this in 2014? -.. note:: This is not entirely true. It is possible to completely disable - email sending, or to have Bugzilla store email messages in a - file instead of sending them. However, this is mainly intended - for testing, as disabling or diverting email on a production - machine would mean that users could miss important events (such - as bug changes or the creation of new accounts). - For more information, see the ``mail_delivery_method`` parameter - in :ref:`parameters`. +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 a Sendmail-compatible MTA, it must be congruent with -at least version 8.7 of Sendmail. +If you are using Sendmail, version 8.7 or higher is required. If you are +using a Sendmail-compatible MTA, it must be compatible with at least version +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 diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst index d33a62f865..582f655212 100644 --- a/docs/en/rst/installing/linux.rst +++ b/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 -scratch, :ref:`quick-start` may be the best instructions for you. +of additional configuration required. -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 ` -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:`-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 -recommend using Apache. However, pretty much any web server that is capable of -running CGI scripts will work. +Any web server that is capable of running CGI scripts can be made to work. +We have specific instructions for the following: .. 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 -need to change are ``$db_driver`` and ``$db_pass``, -respectively the type of the database and the password for -the user you will create for your database. Pick a strong -password (for simplicity, it should not contain single quote -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). +Load this file in your editor. You will need to check/change ``$db_driver`` +and ``$db_pass``, which are respectively the type of the database you are +using and the password for the ``bugs`` database user you have created. +``$db_driver`` can be either ``mysql``, ``Pg`` (PostgreSQL), ``Oracle`` or +``Sqlite``. All values are case-sensitive. 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, -Apache uses the ``www-data`` group. +The default is ``apache``, which is correct for Red Hat and Fedora. On Debian +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 -:file:`checksetup.pl` run. You should go through -the Parameters page and see if there are any you wish to change. -They key parameters are documented in :ref:`parameters`; -you should certainly alter -:command:`maintainer` and :command:`urlbase`; -you may also want to alter -:command:`cookiepath` or :command:`requirelogin`. +Next, do the :ref:`post-install-config`. + +XXXX How to we integrate the below (copied from the wiki)? + +Gentoo +====== -== 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: # emerge -av bugzilla @@ -232,7 +235,8 @@ Else: mysql>CREATE DATABASE databasename;
mysql>GRANT ON databasename.* to 'bugzillauser'@'hostname' identified by 'pa$$w0rd'; -== 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) diff --git a/docs/en/rst/installing/migrating.rst b/docs/en/rst/installing/migrating.rst index 45d2213e07..121f723dd4 100644 --- a/docs/en/rst/installing/migrating.rst +++ b/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 _. +`Bugzilla::Migrate `_. 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 diff --git a/docs/en/rst/installing/mysql.rst b/docs/en/rst/installing/mysql.rst index 20ff67c5f0..67d890a297 100644 --- a/docs/en/rst/installing/mysql.rst +++ b/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] diff --git a/docs/en/rst/installing/optional-features.rst b/docs/en/rst/installing/optional-features.rst deleted file mode 100644 index 37d75494bb..0000000000 --- a/docs/en/rst/installing/optional-features.rst +++ /dev/null @@ -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 && ./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 `_. - -.. _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 && ./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 `_. - -.. _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 && ./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 `_. - -.. _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 -```` section for your -Bugzilla, or in the ```` -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.` in the same location as -the default one (:file:`localconfig`). It also checks for -customized templates in a directory named -:file:`` in the same location as the -default one (:file:`template/`). 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 - - - ServerName foo.bar.baz - SetEnv PROJECT foo - Alias /bugzilla /var/www/bugzilla - - -Don't forget to also export this variable before accessing Bugzilla -by other means, such as cron tasks for instance. - diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst index 3a87e3516c..dd23b4b9ae 100644 --- a/docs/en/rst/installing/quick-start.rst +++ b/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 - password, and write it down. + * When creating the initial Linux user, call it "bugzilla", give it a + 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 - page can validate visually that it's up and running. + It's not really possible to use Bugzilla for real through Lynx, but you + 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:///``, where ```` is probably the "inet addr" - value displayed when you run :command:`ifconfig eth0`. + at ``http:///``, where ```` is (unless you have + 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 - account for your Bugzilla to use at https://gmail.com. Then, open the "Email" - section of the Parameters using the link in the left column, and set the - following parameter values: + use Gmail, so we do that here so you have it working. Visit + https://gmail.com and create a new Gmail account for your Bugzilla to use. + Then, open the "Email" section of the Parameters using the link in the + 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_password: ``the_gmail_password`` + * smtp_username: ``new_gmail_address@gmail.com`` + * smtp_password: ``new_gmail_password`` * smtp_ssl: On Click "Save Changes" at the bottom of the page. diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/upgrading-from-bazaar.rst index 2fb1acfebe..5d10bb4576 100644 --- a/docs/en/rst/upgrading/upgrading-from-bazaar.rst +++ b/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 -version of Bugzilla you are using, to minimise the risk of conflict or -problems. Any major upgrade can then happen -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. +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. 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 `_. XXXmake_common +`download the official build `_. 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 -directory into which the source code will be downloaded. +point release of version $VERSION. :file:`bugzilla-git` is the name of the +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` diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/upgrading-from-cvs.rst index f642fe4529..d3476cee81 100644 --- a/docs/en/rst/upgrading/upgrading-from-cvs.rst +++ b/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. -We might share some text using the include directive -if there is a long enough section to be worth splitting it out. But I'm -not going to fill it in until the Bzr instructions have had a review, +This will be the same as the Bzr instructions but using CVS commands. +There are only 3 bzr commands, so we should be able to share the rest of +the text. + +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. diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst index fb7cc7c9b8..bfa0717eea 100644 --- a/docs/en/rst/upgrading/upgrading-with-git.rst +++ b/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 - upgrade on a development server with the production data. + length of downtime would be a problem for you, you can determine + timings for your particular situation by doing a test upgrade on a + development server with the production data. .. _upgrade-finish: