From: Gervase Markham Date: Wed, 6 Aug 2014 15:49:58 +0000 (+0100) Subject: Work in progress. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=43e95876a85f3d8f4c74d2533bc65744bb7fd2e3;p=thirdparty%2Fbugzilla.git Work in progress. --- diff --git a/docs/en/rst/about/credits.rst b/docs/en/rst/about/credits.rst new file mode 100644 index 0000000000..cce2713003 --- /dev/null +++ b/docs/en/rst/about/credits.rst @@ -0,0 +1,46 @@ +.. _credits: + +Credits +####### + +The people listed below have made enormous contributions to the +creation of this Guide, through their writing, dedicated hacking efforts, +numerous e-mail and IRC support sessions, and overall excellent +contribution to the Bugzilla community: + +Gervase Markham + for entirely rewriting the documentation for Bugzilla 5.0. + +Matthew P. Barnson + for the Herculean task of pulling together the Bugzilla Guide + and shepherding it to 2.14. + +Terry Weissman + for initially writing Bugzilla and creating the README upon + which the UNIX installation documentation is largely based. + +Tara Hernandez + for keeping Bugzilla development going strong after Terry left + mozilla.org and for running landfill. + +Dave Lawrence + for providing insight into the key differences between Red + Hat's customized Bugzilla and stock Bugzilla. + +Dawn Endico + for being a hacker extraordinaire and putting up with Matthew's + incessant questions and arguments on irc.mozilla.org in #mozwebtools + +Jacob Steenhagen + for taking over documentation during the 2.17 development + period. + +Dave Miller + for taking over as project lead when Tara stepped down and + continually pushing for the documentation to be the best it can be. + +Thanks also go to the following people for significant contributions +to this documentation: +Kevin Brannen, Vlad Dascalu, Ben FrantzDale, Eric Hanson, Zach Lipton, +Andrew Pearson, Joe Robins, Spencer Smith, Ron Teitelbaum, Shane Travis, +Martin Wulffeld. diff --git a/docs/en/rst/about/document-conventions.rst b/docs/en/rst/about/document-conventions.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/about/evaluating.rst b/docs/en/rst/about/evaluating.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/about/getting-help.rst b/docs/en/rst/about/getting-help.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/about/introduction.rst b/docs/en/rst/about/introduction.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/gfdl.rst b/docs/en/rst/about/license.rst similarity index 100% rename from docs/en/rst/gfdl.rst rename to docs/en/rst/about/license.rst diff --git a/docs/en/rst/administration.rst b/docs/en/rst/administering.rst similarity index 100% rename from docs/en/rst/administration.rst rename to docs/en/rst/administering.rst diff --git a/docs/en/rst/administering/flags.rst b/docs/en/rst/administering/flags.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/groups.rst b/docs/en/rst/administering/groups.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/keywords.rst b/docs/en/rst/administering/keywords.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/preferences.rst b/docs/en/rst/administering/preferences.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/products.rst b/docs/en/rst/administering/products.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/users.rst b/docs/en/rst/administering/users.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/versions-and-milestones.rst b/docs/en/rst/administering/versions-and-milestones.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/whining.rst b/docs/en/rst/administering/whining.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/administering/workflow.rst b/docs/en/rst/administering/workflow.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/customization.rst b/docs/en/rst/customizing.rst similarity index 100% rename from docs/en/rst/customization.rst rename to docs/en/rst/customizing.rst diff --git a/docs/en/rst/customizing/existing-parameters.rst b/docs/en/rst/customizing/existing-parameters.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/customizing/extensions.rst b/docs/en/rst/customizing/extensions.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/customizing/languages.rst b/docs/en/rst/customizing/languages.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/customizing/skins.rst b/docs/en/rst/customizing/skins.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/customizing/templates.rst b/docs/en/rst/customizing/templates.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/customizing/who-can-change-what.rst b/docs/en/rst/customizing/who-can-change-what.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/customizing/writing-extensions.rst b/docs/en/rst/customizing/writing-extensions.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/extensions/example.rst b/docs/en/rst/extensions/example.rst new file mode 100644 index 0000000000..07b355887f --- /dev/null +++ b/docs/en/rst/extensions/example.rst @@ -0,0 +1,22 @@ +Example +####### + +This is a sample documentation file for the Example extension. Like all of +the Bugzilla docs, it's written in +`reStructured Text (reST) format `_ +and will be compiled by `Sphinx `_. + +If you build the docs yourself using :file:`makedocs.pl`, this file will get +incorporated into the Extensions chapter, as will any documentation +you write for your extensions which fulfils the following criteria: + +* In the :file:`extensions/YourExtension/doc/` directory +* Has a :file:`.rst` file extension + +You are recommended to make the name of your reST doc file the same as the +name of your extension, so that there is no clash when all the extension +documentation is copied into the same directory. So, for example, this file +is called :file:`example.rst`, as it's part of the Example extension. If you +need multiple documentation files, prefix the filename with the name of your +extension, e.g. :file:`example-extra.rst`. + diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst index f2bd14f18b..c7e65d71d0 100644 --- a/docs/en/rst/index.rst +++ b/docs/en/rst/index.rst @@ -1,8 +1,3 @@ -.. Bugzilla documentation master file, created by - sphinx-quickstart on Tue Sep 3 16:11:00 2013. - You can adapt this file completely to your liking, but it should at least - contain the root `toctree` directive. - Bugzilla Documentation ====================== @@ -11,13 +6,10 @@ Bugzilla Documentation :numbered: about - installation - administration - security + installing + upgrading + maintaining + customizing + integrating + administering using - extensions - customization - patches - troubleshooting - modules - gfdl diff --git a/docs/en/rst/installation.rst b/docs/en/rst/installing.rst similarity index 99% rename from docs/en/rst/installation.rst rename to docs/en/rst/installing.rst index ef7423d2de..4aca12176c 100644 --- a/docs/en/rst/installation.rst +++ b/docs/en/rst/installing.rst @@ -127,22 +127,7 @@ PostgreSQL server is started when the machine boots. Oracle ------ -Installed Version Test: - -.. code-block:: sql - - SELECT * FROM v$version - -(you first have to log in into your DB) - -If you don't have it and your OS doesn't provide official packages, -visit ``_. You need Oracle -version 10.02.0 or higher. - -If you install from something other than a packaging/installation -system, such as .rpm (RPM Package Manager), .deb (Debian Package), .exe -(Windows Executable), or .msi (Windows Installer), make sure the -Oracle server is started when the machine boots. +XXX Need to replace instructions for Oracle .. _install-webserver: diff --git a/docs/en/rst/installing/email.rst b/docs/en/rst/installing/email.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/installing/mac-os-x.rst b/docs/en/rst/installing/mac-os-x.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/installing/migrating.rst b/docs/en/rst/installing/migrating.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/installing/moving.rst b/docs/en/rst/installing/moving.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/installing/optional-features.rst b/docs/en/rst/installing/optional-features.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/installing/windows.rst b/docs/en/rst/installing/windows.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/integrating.rst b/docs/en/rst/integrating.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/integrating/apis.rst b/docs/en/rst/integrating/apis.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/integrating/tips.rst b/docs/en/rst/integrating/tips.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/maintaining.rst b/docs/en/rst/maintaining.rst new file mode 100644 index 0000000000..532bf97943 --- /dev/null +++ b/docs/en/rst/maintaining.rst @@ -0,0 +1,5 @@ +Maintaining Bugzilla +==================== + +.. toctree:: + :maxdepth: 2 diff --git a/docs/en/rst/maintaining/backups.rst b/docs/en/rst/maintaining/backups.rst new file mode 100644 index 0000000000..039dbaf03c --- /dev/null +++ b/docs/en/rst/maintaining/backups.rst @@ -0,0 +1,16 @@ +.. _backups: + +Making Backups +############## + + Here are some sample commands you could use to backup + your database, depending on what database system you're + using. You may have to modify these commands for your + particular setup. + + MySQL: + mysqldump --opt -u bugs -p bugs > bugs.sql + PostgreSQL: + pg_dump --no-privileges --no-owner -h localhost -U bugs + > bugs.sql + diff --git a/docs/en/rst/maintaining/merging-accounts.rst b/docs/en/rst/maintaining/merging-accounts.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/maintaining/sanity-check.rst b/docs/en/rst/maintaining/sanity-check.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/modules.rst b/docs/en/rst/modules.rst deleted file mode 100644 index 4740161805..0000000000 --- a/docs/en/rst/modules.rst +++ /dev/null @@ -1,126 +0,0 @@ -.. highlight:: console - -.. _install-perlmodules-manual: - -=================================== -Manual Installation of Perl Modules -=================================== - -.. _modules-manual-instructions: - -Instructions -############ - -If you need to install Perl modules manually, here's how it's done. -Download the module using the link given in the next section, and then -apply this magic incantation, as root: - -:: - - # tar -xzvf .tar.gz - # cd - # perl Makefile.PL - # make - # make test - # make install - -.. note:: In order to compile source code under Windows you will need to obtain - a 'make' utility. The :command:`nmake` utility provided with - Microsoft Visual C++ may be used. As an alternative, there is a - utility called :command:`dmake` available from CPAN which is - written entirely in Perl. - As described in :ref:`modules-manual-download`, however, most - packages already exist and are available from ActiveState or theory58S. - We highly recommend that you install them using the ppm GUI available with - ActiveState and to add the theory58S repository to your list of repositories. - -.. _modules-manual-download: - -Download Locations -################## - -.. note:: Running Bugzilla on Windows requires the use of ActiveState - Perl |min-perl-ver| or higher. Many modules already exist in the core - distribution of ActiveState Perl. Additional modules can be downloaded - from ``_ - if you use Perl |min-perl-ver|. - -CGI: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -Data-Dumper: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -Date::Format (part of TimeDate): - -* CPAN Download Page: ``_ -* Documentation: ``_ - -DBI: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -DBD::mysql: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -DBD::Pg: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -Template-Toolkit: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -GD: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -Template::Plugin::GD: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -MIME::Parser (part of MIME-tools): - -* CPAN Download Page: ``_ -* Documentation: ``_ - -.. _modules-manual-optional: - -Optional Modules -################ - -Chart::Lines: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -GD::Graph: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -GD::Text::Align (part of GD::Text::Util): - -* CPAN Download Page: ``_ -* Documentation: ``_ - -XML::Twig: - -* CPAN Download Page: ``_ -* Documentation: ``_ - -PatchReader: - -* CPAN Download Page: ``_ -* Documentation: ``_ diff --git a/docs/en/rst/patches.rst b/docs/en/rst/patches.rst deleted file mode 100644 index 688d17105d..0000000000 --- a/docs/en/rst/patches.rst +++ /dev/null @@ -1,88 +0,0 @@ - - -.. _patches: - -======= -Contrib -======= - -There are a number of unofficial Bugzilla add-ons in the -:file:`$BUGZILLA_ROOT/contrib/` -directory. This section documents them. - -.. _cmdline: - -Command-line Search Interface -############################# - -There are a suite of Unix utilities for searching Bugzilla from the -command line. They live in the -:file:`contrib/cmdline` directory. -There are three files - :file:`query.conf`, -:file:`buglist` and :file:`bugs`. - -.. warning:: These files pre-date the templatization work done as part of the - 2.16 release, and have not been updated. - -:file:`query.conf` contains the mapping from -options to field names and comparison types. Quoted option names -are ``grepped`` for, so it should be easy to edit this -file. Comments (#) have no effect; you must make sure these lines -do not contain any quoted ``option``. - -:file:`buglist` is a shell script that submits a -Bugzilla query and writes the resulting HTML page to stdout. -It supports both short options, (such as ``-Afoo`` -or ``-Rbar``) and long options (such -as ``--assignedto=foo`` or ``--reporter=bar``). -If the first character of an option is not ``-``, it is -treated as if it were prefixed with ``--default=``. - -The column list is taken from the COLUMNLIST environment variable. -This is equivalent to the ``Change Columns`` option -that is available when you list bugs in buglist.cgi. If you have -already used Bugzilla, grep for COLUMNLIST in your cookies file -to see your current COLUMNLIST setting. - -:file:`bugs` is a simple shell script which calls -:file:`buglist` and extracts the -bug numbers from the output. Adding the prefix -``http://bugzilla.mozilla.org/buglist.cgi?bug_id=`` -turns the bug list into a working link if any bugs are found. -Counting bugs is easy. Pipe the results through -:command:`sed -e 's/,/ /g' | wc | awk '{printf $2 "\\n"}'` - -Akkana Peck says she has good results piping -:file:`buglist` output through -:command:`w3m -T text/html -dump` - -.. _cmdline-bugmail: - -Command-line 'Send Unsent Bug-mail' tool -######################################## - -Within the :file:`contrib` directory -exists a utility with the descriptive (if compact) name -of :file:`sendunsentbugmail.pl`. The purpose of this -script is, simply, to send out any bug-related mail that should -have been sent by now, but for one reason or another has not. - -To accomplish this task, :file:`sendunsentbugmail.pl` uses -the same mechanism as the :file:`sanitycheck.cgi` script; -it scans through the entire database looking for bugs with changes that -were made more than 30 minutes ago, but where there is no record of -anyone related to that bug having been sent mail. Having compiled a list, -it then uses the standard rules to determine who gets mail, and sends it -out. - -As the script runs, it indicates the bug for which it is currently -sending mail; when it has finished, it gives a numerical count of how -many mails were sent and how many people were excluded. (Individual -user names are not recorded or displayed.) If the script produces -no output, that means no unsent mail was detected. - -*Usage*: move the sendunsentbugmail.pl script -up into the main directory, ensure it has execute permission, and run it -from the command line (or from a cron job) with no parameters. - - diff --git a/docs/en/rst/troubleshooting.rst b/docs/en/rst/troubleshooting.rst deleted file mode 100644 index 64b9263a45..0000000000 --- a/docs/en/rst/troubleshooting.rst +++ /dev/null @@ -1,239 +0,0 @@ -.. highlight:: console - -.. _troubleshooting: - -=============== -Troubleshooting -=============== - -This section gives solutions to common Bugzilla installation -problems. If none of the section headings seems to match your -problem, read the general advice. - -.. _general-advice: - -General Advice -############## - -If you can't get :file:`checksetup.pl` to run to -completion, it normally explains what's wrong and how to fix it. -If you can't work it out, or if it's being uncommunicative, post -the errors in the -`mozilla.support.bugzilla `_ -newsgroup. - -If you have made it all the way through -:ref:`installation` (Installation) and -:ref:`configuration` (Configuration) but accessing the Bugzilla -URL doesn't work, the first thing to do is to check your web server error -log. For Apache, this is often located at -:file:`/etc/logs/httpd/error_log`. The error messages -you see may be self-explanatory enough to enable you to diagnose and -fix the problem. If not, see below for some commonly-encountered -errors. If that doesn't help, post the errors to the newsgroup. - -Bugzilla can also log all user-based errors (and many code-based errors) -that occur, without polluting the web server's error log. To enable -Bugzilla error logging, create a file that Bugzilla can write to, named -:file:`errorlog`, in the Bugzilla :file:`data` -directory. Errors will be logged as they occur, and will include the type -of the error, the IP address and username (if available) of the user who -triggered the error, and the values of all environment variables; if a -form was being submitted, the data in the form will also be included. -To disable error logging, delete or rename the -:file:`errorlog` file. - -.. _trbl-testserver: - -The Apache web server is not serving Bugzilla pages -################################################### - -After you have run :command:`checksetup.pl` twice, -run :command:`testserver.pl http://yoursite.yourdomain/yoururl` -to confirm that your web server is configured properly for -Bugzilla. - -:: - - $ ./testserver.pl http://landfill.bugzilla.org/bugzilla-tip - TEST-OK Webserver is running under group id in $webservergroup. - TEST-OK Got ant picture. - TEST-OK Webserver is executing CGIs. - TEST-OK Webserver is preventing fetch of http://landfill.bugzilla.org/bugzilla-tip/localconfig. - -.. _trbl-perlmodule: - -I installed a Perl module, but :file:`checksetup.pl` claims it's not installed! -############################################################################### - -This could be caused by one of two things: - -#. You have two versions of Perl on your machine. You are installing - modules into one, and Bugzilla is using the other. Rerun the CPAN - commands (or manual compile) using the full path to Perl from the - top of :file:`checksetup.pl`. This will make sure you - are installing the modules in the right place. - -#. The permissions on your library directories are set incorrectly. - They must, at the very least, be readable by the web server user or - group. It is recommended that they be world readable. - -.. _trbl-dbdSponge: - -DBD::Sponge::db prepare failed -############################## - -The following error message may appear due to a bug in DBD::mysql -(over which the Bugzilla team have no control): - -:: - - DBD::Sponge::db prepare failed: Cannot determine NUM_OF_FIELDS at D:/Perl/site/lib/DBD/mysql.pm line 248. - SV = NULL(0x0) at 0x20fc444 - REFCNT = 1 - FLAGS = (PADBUSY,PADMY) - -To fix this, go to -:file:`/lib/DBD/sponge.pm` -in your Perl installation and replace - -.. code-block:: perl - - my $numFields; - if ($attribs->{'NUM_OF_FIELDS'}) { - $numFields = $attribs->{'NUM_OF_FIELDS'}; - } - elsif ($attribs->{'NAME'}) { - $numFields = @{$attribs->{NAME}}; - } - -with - -.. code-block:: perl - - my $numFields; - if ($attribs->{'NUM_OF_FIELDS'}) { - $numFields = $attribs->{'NUM_OF_FIELDS'}; - } - elsif ($attribs->{'NAMES'}) { - $numFields = @{$attribs->{NAMES}}; - } - -(note the S added to NAME.) - -.. _paranoid-security: - -cannot chdir(/var/spool/mqueue) -############################### - -If you are installing Bugzilla on SuSE Linux, or some other -distributions with ``paranoid`` security options, it is -possible that the checksetup.pl script may fail with the error: -:: - - cannot chdir(/var/spool/mqueue): Permission denied - -This is because your :file:`/var/spool/mqueue` -directory has a mode of ``drwx------``. -Type :command:`chmod 755 :file:`/var/spool/mqueue`` -as root to fix this problem. This will allow any process running on your -machine the ability to *read* the -:file:`/var/spool/mqueue` directory. - -.. _trbl-relogin-everyone: - -Everybody is constantly being forced to relogin -############################################### - -The most-likely cause is that the ``cookiepath`` parameter -is not set correctly in the Bugzilla configuration. You can change this (if -you're a Bugzilla administrator) from the editparams.cgi page via the web interface. - -The value of the cookiepath parameter should be the actual directory -containing your Bugzilla installation, *as seen by the end-user's -web browser*. Leading and trailing slashes are mandatory. You can -also set the cookiepath to any directory which is a parent of the Bugzilla -directory (such as '/', the root directory). But you can't put something -that isn't at least a partial match or it won't work. What you're actually -doing is restricting the end-user's browser to sending the cookies back only -to that directory. - -How do you know if you want your specific Bugzilla directory or the -whole site? - -If you have only one Bugzilla running on the server, and you don't -mind having other applications on the same server with it being able to see -the cookies (you might be doing this on purpose if you have other things on -your site that share authentication with Bugzilla), then you'll want to have -the cookiepath set to "/", or to a sufficiently-high enough directory that -all of the involved apps can see the cookies. - -.. _trbl-relogin-everyone-share: - -Examples of urlbase/cookiepath pairs for sharing login cookies -============================================================== - -| urlbase is http://bugzilla.mozilla.org/ -| cookiepath is / - - -| urlbase is http://tools.mysite.tld/bugzilla/ -| but you have http://tools.mysite.tld/someotherapp/ which shares -| authentication with your Bugzilla -| -| cookiepath is / - -On the other hand, if you have more than one Bugzilla running on the -server (some people do - we do on landfill) then you need to have the -cookiepath restricted enough so that the different Bugzillas don't -confuse their cookies with one another. - -.. _trbl-relogin-everyone-restrict: - -Examples of urlbase/cookiepath pairs to restrict the login cookie -================================================================= - -| urlbase is http://landfill.bugzilla.org/bugzilla-tip/ -| cookiepath is /bugzilla-tip/ - -| urlbase is http://landfill.bugzilla.org/bugzilla-4.0-branch/ -| cookiepath is /bugzilla-4.0-branch/ - -If you had cookiepath set to ``/`` at any point in the -past and need to set it to something more restrictive -(i.e. ``/bugzilla/``), you can safely do this without -requiring users to delete their Bugzilla-related cookies in their -browser (this is true starting with Bugzilla 2.18 and Bugzilla 2.16.5). - -.. _trbl-index: - -:file:`index.cgi` doesn't show up unless specified in the URL -############################################################# - -You probably need to set up your web server in such a way that it -will serve the index.cgi page as an index page. - -If you are using Apache, you can do this by adding -:file:`index.cgi` to the end of the -``DirectoryIndex`` line -as mentioned in :ref:`http-apache`. - -.. _trbl-passwd-encryption: - -checksetup.pl reports "Client does not support authentication protocol requested by server..." -############################################################################################## - -This error is occurring because you are using the new password -encryption that comes with MySQL 4.1, while your -:file:`DBD::mysql` module was compiled against an -older version of MySQL. If you recompile :file:`DBD::mysql` -against the current MySQL libraries (or just obtain a newer version -of this module) then the error may go away. - -If that does not fix the problem, or if you cannot recompile the -existing module (e.g. you're running Windows) and/or don't want to -replace it (e.g. you want to keep using a packaged version), then a -workaround is available from the MySQL docs: -``_ - - diff --git a/docs/en/rst/upgrading.rst b/docs/en/rst/upgrading.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/upgrading/overview.rst b/docs/en/rst/upgrading/overview.rst new file mode 100644 index 0000000000..297d63c16a --- /dev/null +++ b/docs/en/rst/upgrading/overview.rst @@ -0,0 +1,42 @@ +Overview +######## + +You can upgrade Bugzilla from any version to any later version in one go - +there is no need to pass through intermediate versions unless you are changing +the method by which you obtain the code along the way. + +Bugzilla uses the Git version control system to store its code. A modern Bugzilla +installation consists of a checkout of a stable version of the code from our +Git repository. This makes upgrading much easier. If this is +true of you, see :ref:`upgrading-with-git`. + +Before Git, we used to use Bazaar and, before that, CVS. If your installation +of Bugzilla consists of a checkout from one of those two systems, you need to +upgrade in three steps: + +1. upgrade to the latest point release of your current Bugzilla version; +2. move to Git while staying on exactly the same release; +3. upgrade to the latest Bugzilla using the instructions for :ref:`upgrading-with-git`. + +See :ref:`upgrading-from-bazaar` or :ref:`upgrading-from-cvs` as appropriate. + +Some Bugzillas were installed simply by downloading a copy of the code as +an archive file ("tarball"). However, recent tarballs have included source +code management system information, so you may be able to use the Git, Bzr +or CVS instructions. + +If you aren't sure which of these categories you fall into, to find out which +version control system your copy of Bugzilla recognizes, look for the +following subdirectories in your root Bugzilla directory: + +* :file:`.git`: you installed using Git - follow :ref:`upgrading-with-git` +* :file:`.bzr`: you installed using Bazaar - follow :ref:`upgrading-from-bazaar` +* :file:`CVS`: you installed using CVS - follow :ref:`upgrading-from-cvs` +* none of the above: you installed using an old tarball - follow :ref:`upgrading-with-a-tarball` + +It is also possible, particularly if your server machine does not have and +cannot be configured to have access to the public internet, to upgrade using +a tarball. See :ref:`upgrading-with-a-tarball`. + +Before performing any upgrade, it's a good idea to back up both your Bugzilla +directory and your database. XXXlink to backup info in Maintenance diff --git a/docs/en/rst/upgrading/upgrading-from-a-tarball.rst b/docs/en/rst/upgrading/upgrading-from-a-tarball.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/upgrading/upgrading-from-bazaar.rst b/docs/en/rst/upgrading/upgrading-from-bazaar.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/upgrading/upgrading-from-cvs.rst b/docs/en/rst/upgrading/upgrading-from-cvs.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst new file mode 100644 index 0000000000..9a41ba76c1 --- /dev/null +++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst @@ -0,0 +1,45 @@ +.. _upgrading-with-a-tarball: + +Upgrading with a Tarball +######################## + +If you are unable (or unwilling) to use Bzr, another option that's +always available is to obtain the latest tarball from the `Download Page `_ and +create a new Bugzilla installation from that. + +This sequence of commands shows how to get the tarball from the +command-line; it is also possible to download it from the site +directly in a web browser. If you go that route, save the file +to the :file:`/var/www/html` +directory (or its equivalent, if you use something else) and +omit the first three lines of the example. + +:: + + $ cd /var/www/html + $ wget http://ftp.mozilla.org/pub/mozilla.org/webtools/bugzilla-4.2.1.tar.gz + ... + $ tar xzvf bugzilla-4.2.1.tar.gz + bugzilla-4.2.1/ + bugzilla-4.2.1/colchange.cgi + ... + $ cd bugzilla-4.2.1 + $ cp ../bugzilla/localconfig* . + $ cp -r ../bugzilla/data . + $ cd .. + $ mv bugzilla bugzilla.old + $ mv bugzilla-4.2.1 bugzilla + +.. warning:: The :command:`cp` commands both end with periods which + is a very important detail--it means that the destination + directory is the current working directory. + +.. warning:: If you have some extensions installed, you will have to copy them + to the new bugzilla directory too. Extensions are located in :file:`bugzilla/extensions/`. + Only copy those you + installed, not those managed by the Bugzilla team. + +This upgrade method will give you a clean install of Bugzilla. +That's fine if you don't have any local customizations that you +want to maintain. If you do have customizations, then you will +need to reapply them by hand to the appropriate files. diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/using/creating-an-account.rst b/docs/en/rst/using/creating-an-account.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/using/editing.rst b/docs/en/rst/using/editing.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/using/filing.rst b/docs/en/rst/using/filing.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/using/finding.rst b/docs/en/rst/using/finding.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/using/preferences.rst b/docs/en/rst/using/preferences.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/using/tips.rst b/docs/en/rst/using/tips.rst new file mode 100644 index 0000000000..e69de29bb2 diff --git a/docs/en/rst/using/understanding.rst b/docs/en/rst/using/understanding.rst new file mode 100644 index 0000000000..e69de29bb2