From: Gervase Markham Date: Wed, 26 Nov 2014 16:04:32 +0000 (+0000) Subject: Big rearrangement, as discussed in public meeting. Plus resolve lots of TODOs. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=1b95c324e91fb8a074c2c7d677685067500a6470;p=thirdparty%2Fbugzilla.git Big rearrangement, as discussed in public meeting. Plus resolve lots of TODOs. --- diff --git a/docs/en/rst/about/index.rst b/docs/en/rst/about/index.rst index 3c0d19ca5e..239c6ecea5 100644 --- a/docs/en/rst/about/index.rst +++ b/docs/en/rst/about/index.rst @@ -1,8 +1,8 @@ .. _about: -================ -About This Guide -================ +======================== +About This Documentation +======================== This is the documentation for version |version| of Bugzilla, a bug-tracking system from Mozilla. Bugzilla is an enterprise-class piece of software diff --git a/docs/en/rst/administering/index.rst b/docs/en/rst/administering/index.rst index 5f8b3ccc0b..c478193231 100644 --- a/docs/en/rst/administering/index.rst +++ b/docs/en/rst/administering/index.rst @@ -1,8 +1,8 @@ .. _administering: -====================== -Administering Bugzilla -====================== +==================== +Administration Guide +==================== For those with :group:`admin` privileges, Bugzilla can be administered using the :guilabel:`Administration` link in the header. The administrative diff --git a/docs/en/rst/administering/keywords.rst b/docs/en/rst/administering/keywords.rst index a7b9efd018..245bcbe4c8 100644 --- a/docs/en/rst/administering/keywords.rst +++ b/docs/en/rst/administering/keywords.rst @@ -7,17 +7,10 @@ The administrator can define keywords which can be used to tag and categorise bugs. For example, the keyword "regression" is commonly used. A company might have a policy stating all regressions must be fixed by the next release—this keyword can make tracking those -bugs much easier. - -Keywords are global, rather than per product. If the administrator changes -a keyword currently applied to any bugs, the keyword cache must be rebuilt -using the :ref:`sanity-check` script. - -.. todo:: Does this mean changing the name of the keyword? Is it still true? - -Currently keywords cannot be marked obsolete to prevent future usage. +bugs much easier. Keywords are global, rather than per product. Keywords can be created, edited, or deleted by clicking the "Keywords" link in the admin page. There are two fields for each keyword—the keyword -itself and a brief description. +itself and a brief description. Currently keywords cannot be marked obsolete +to prevent future usage. diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst index 2af178b6ae..8e3e612315 100644 --- a/docs/en/rst/administering/parameters.rst +++ b/docs/en/rst/administering/parameters.rst @@ -78,18 +78,6 @@ shutdownhtml Bugzilla pages for all users, including Admins. Used in the event of site maintenance or outage situations. - .. note:: Although regular log-in capability is disabled - while :param:`shutdownhtml` - is enabled, safeguards are in place to protect the unfortunate - admin who loses connection to Bugzilla. Should this happen to you, - go directly to the :file:`editparams.cgi` (by typing - the URL in manually, if necessary). Doing this will prompt you to - log in, and your name/password will be accepted here (but nowhere - else). - - .. todo:: Is this still true? The editparams.cgi code seems to - call using LOGIN_REQUIRED in the conventional manner... - announcehtml Any text in this field will be displayed at the top of every HTML page in this Bugzilla installation. The text is not wrapped in any @@ -408,7 +396,7 @@ makeproductgroups used for querying bugs. .. todo:: This is spectacularly unclear. I have no idea what makeproductgroups - does - can someone explain it to me? + does - can someone explain it to me? Convert this item into a bug on checkin. chartgroup The name of the group of users who can use the 'New Charts' feature. Administrators should ensure that the public categories and series definitions do not divulge confidential information before enabling this for an untrusted population. If left blank, no users will be able to use New Charts. diff --git a/docs/en/rst/customizing/extensions.rst b/docs/en/rst/customizing/extensions.rst deleted file mode 100644 index 73e8d58ad2..0000000000 --- a/docs/en/rst/customizing/extensions.rst +++ /dev/null @@ -1,15 +0,0 @@ -.. _extensions: - -Extensions -########## - -One of the best ways to customize Bugzilla is by using a Bugzilla -Extension. Extensions can modify both the code and UI of Bugzilla in a way -that can be distributed to other Bugzilla users and ported forward to future -versions of Bugzilla with minimal effort. - -We maintain a -`list of available extensions `_ -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 `. diff --git a/docs/en/rst/customizing/index.rst b/docs/en/rst/customizing/index.rst deleted file mode 100644 index d6c41e9f25..0000000000 --- a/docs/en/rst/customizing/index.rst +++ /dev/null @@ -1,22 +0,0 @@ -.. highlight:: perl - -.. _customizing: - -==================== -Customizing Bugzilla -==================== - -You may find that Bugzilla already does what you want it to do, you just -need to configure it correctly. Read the :ref:`administering` sections -carefully to see if that's the case for you. If not, then this chapter -explains how to use the available mechanisms for customization. - -.. toctree:: - :maxdepth: 2 - - faq - extensions - skins - languages - templates - writing-extensions diff --git a/docs/en/rst/index.rst b/docs/en/rst/index.rst index 7a597a855f..e95560e8e0 100644 --- a/docs/en/rst/index.rst +++ b/docs/en/rst/index.rst @@ -3,17 +3,14 @@ Bugzilla Documentation ====================== .. toctree:: - :maxdepth: 2 + :maxdepth: 1 :numbered: 4 about/index + using/index installing/index - upgrading/index - maintaining/index - customizing/index - integrating/index administering/index - using/index + integrating/index .. toctree:: :hidden: diff --git a/docs/en/rst/installing/apache-windows.rst b/docs/en/rst/installing/apache-windows.rst index 10bf1c6dbf..5e8ac89288 100644 --- a/docs/en/rst/installing/apache-windows.rst +++ b/docs/en/rst/installing/apache-windows.rst @@ -115,7 +115,8 @@ in its log files. #. Replace ``%r`` with ``%m %U``. -.. todo:: Is this the right line? Or given how we've configured it above, is it not a vhost? +(If you have configured Apache differently, a different log line might apply. +Adjust these instructions accordingly.) Restart Apache ============== diff --git a/docs/en/rst/maintaining/backups.rst b/docs/en/rst/installing/backups.rst similarity index 91% rename from docs/en/rst/maintaining/backups.rst rename to docs/en/rst/installing/backups.rst index 384c79437b..f20b3021ab 100644 --- a/docs/en/rst/maintaining/backups.rst +++ b/docs/en/rst/installing/backups.rst @@ -21,7 +21,7 @@ See the `mysqldump documentation `_ for more information on :file:`mysqldump`. -.. todo:: Mention max_allowed_packet? +.. todo:: Mention max_allowed_packet? Convert this item to a bug on checkin. PostgreSQL ---------- diff --git a/docs/en/rst/installing/essential-post-install-config.rst b/docs/en/rst/installing/essential-post-install-config.rst index 3882c16a28..c5e9c0bc14 100644 --- a/docs/en/rst/installing/essential-post-install-config.rst +++ b/docs/en/rst/installing/essential-post-install-config.rst @@ -168,3 +168,5 @@ Once you've created your own, you will want to delete TestProduct (which will delete TestComponent automatically). Note that if you've filed a bug in TestProduct to try Bugzilla out, you'll need to move it elsewhere before it's possible to delete TestProduct. + +Now, you may want to do some of the :ref:`optional-post-install-config`. diff --git a/docs/en/rst/installing/index.rst b/docs/en/rst/installing/index.rst index ab818d26a1..91a81bede6 100644 --- a/docs/en/rst/installing/index.rst +++ b/docs/en/rst/installing/index.rst @@ -2,14 +2,14 @@ .. _installing: -=================== -Installing Bugzilla -=================== +================================== +Installation and Maintenance Guide +================================== .. 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. You may want to read :ref:`using`. + your web browser. You may want to read the :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 @@ -19,7 +19,7 @@ operating system that provides an ideal environment for Bugzilla. In that case, you may want to read the :ref:`Quick Start instructions `. .. toctree:: - :maxdepth: 2 + :maxdepth: 1 quick-start linux @@ -29,3 +29,8 @@ case, you may want to read the :ref:`Quick Start instructions `. optional-post-install-config migrating moving + upgrading + backups + sanity-check + merging-accounts + multiple-bugzillas diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst index 3f4cb9169e..97192fac3a 100644 --- a/docs/en/rst/installing/linux.rst +++ b/docs/en/rst/installing/linux.rst @@ -12,11 +12,6 @@ of additional configuration required. If you are installing your machine from scratch, :ref:`quick-start` may be the best instructions for you. -.. todo:: What's our current position on Debian/Ubuntu packages of Bugzilla? Are - there any, and are they any good? - -.. todo:: Which versions of RHEL have packages new enough for us to support them? - .. _linux-install-packages: Install Packages @@ -50,28 +45,26 @@ If you want to install a version of Bugzilla from the Bugzilla project, you will instead need: :command:`yum install httpd mysql-server mod_perl mod_perl-devel httpd-devel -graphviz patchutils gcc perl(Apache2::SizeLimit) perl(Authen::Radius) -perl(Authen::SASL) perl(Cache::Memcached) perl(CGI) perl(Chart::Lines) -perl(Daemon::Generic) perl(Date::Format) perl(DateTime) -perl(DateTime::TimeZone) perl(DBI) perl(Digest::SHA) perl(Email::MIME) -perl(Email::MIME::Attachment::Stripper) perl(Email::Reply) perl(Email::Sender) -perl(Encode) perl(Encode::Detect) perl(File::MimeInfo::Magic) -perl(File::Slurp) perl(GD) perl(GD::Graph) perl(GD::Text) -perl(HTML::FormatText::WithLinks) perl(HTML::Parser) perl(HTML::Scrubber) -perl(IO::Scalar) perl(JSON::RPC) perl(JSON::XS) perl(List::MoreUtils) -perl(LWP::UserAgent) perl(Math::Random::ISAAC) perl(MIME::Parser) -perl(mod_perl2) perl(Net::LDAP) perl(Net::SMTP::SSL) perl(PatchReader) -perl(SOAP::Lite) perl(Template) perl(Template::Plugin::GD::Image) -perl(Test::Taint) perl(TheSchwartz) perl(URI) perl(XMLRPC::Lite) -perl(XML::Twig)` - -.. todo:: Converted to perl() form as per glob's request using info in - Requirements.pm, but I have no idea if that's exactly right... +graphviz patchutils gcc 'perl(Apache2::SizeLimit)' 'perl(Authen::Radius)' +'perl(Authen::SASL)' 'perl(Cache::Memcached)' 'perl(CGI)' 'perl(Chart::Lines)' +'perl(Daemon::Generic)' 'perl(Date::Format)' 'perl(DateTime)' +'perl(DateTime::TimeZone)' 'perl(DBI)' 'perl(Digest::SHA)' 'perl(Email::MIME)' +'perl(Email::MIME::Attachment::Stripper)' 'perl(Email::Reply)' +'perl(Email::Sender)' 'perl(Encode)' 'perl(Encode::Detect)' +'perl(File::MimeInfo::Magic)' 'perl(File::Slurp)' 'perl(GD)' 'perl(GD::Graph)' +'perl(GD::Text)' 'perl(HTML::FormatText::WithLinks)' 'perl(HTML::Parser)' +'perl(HTML::Scrubber)' 'perl(IO::Scalar)' 'perl(JSON::RPC)' 'perl(JSON::XS)' +'perl(List::MoreUtils)' 'perl(LWP::UserAgent)' 'perl(Math::Random::ISAAC)' +'perl(MIME::Parser)' 'perl(mod_perl2)' 'perl(Net::LDAP)' 'perl(Net::SMTP::SSL)' +'perl(PatchReader)' 'perl(SOAP::Lite)' 'perl(Template)' +'perl(Template::Plugin::GD::Image)' 'perl(Test::Taint)' 'perl(TheSchwartz)' +'perl(URI)' 'perl(XMLRPC::Lite)' 'perl(XML::Twig)'` If you are running RHEL6, you will have to enable the "RHEL Server Optional" channel in RHN to get some of those packages. -.. todo:: Add Sqlite RPMs +If you plan to use SQlite as your database, you will need to also install +the appropriate packages for that. Ubuntu and Debian ----------------- @@ -92,7 +85,8 @@ 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 graphviz` -.. todo:: Add Sqlite debs +If you plan to use SQlite as your database, you will need to also install +the appropriate packages for that. Gentoo ------ @@ -144,14 +138,6 @@ server's configuration. includes any directory which is configured using the ``ScriptAlias`` directive of Apache. -Once all the files are in a web accessible directory, make that -directory writable by your web server's user. This is a temporary step -until you run the :file:`checksetup.pl` script, which locks down your -installation. - -.. todo:: Why is this necessary? What does the webserver write there before - checksetup.pl is run? - .. _linux-install-perl-modules: Perl Modules @@ -163,19 +149,21 @@ times, Bugzilla may require a version of a Perl module newer than the one your distribution packages, in which case you will need to install a Bugzilla-only copy of the newer version. -At this point, you need to :file:`su` to root. You should remain as root -until the end of the install. - -.. todo:: Is this true, if they are installing modules locally? +At this point you probably need to become ``root``, e.g. by using +:command:`su`. You should remain as root until the end of the install. This +can be avoided in some circumstances if you are a member of your webserver's +group, but being root is easier and will always work. -To check whether you have all the required modules and what is still missing, -run: +To check whether you have all the required modules, run: :command:`./checksetup.pl --check-modules` You can run this command as many times as necessary. -Install all missing modules locally like this: +If you have not already installed the necessary modules, and want to do it +system-wide, invoke your package manager appropriately at this point. +Alternatively, you can install all missing modules locally (i.e. just for +Bugzilla) like this: :command:`./install-module.pl --all` @@ -191,7 +179,8 @@ Or, you can pass an individual module name: distribution you are using, but are often called :file:`-devel`. - .. todo:: Give examples for Debian/Ubuntu and RedHat? + .. todo:: Give examples for Debian/Ubuntu and RedHat. + Convert this item to a bug after checkin. .. _linux-config-webserver: diff --git a/docs/en/rst/installing/mac-os-x.rst b/docs/en/rst/installing/mac-os-x.rst index 3d9c64355a..545d2fa278 100644 --- a/docs/en/rst/installing/mac-os-x.rst +++ b/docs/en/rst/installing/mac-os-x.rst @@ -5,6 +5,11 @@ Mac OS X .. _macosx-install-packages: +.. note:: The Bugzilla team has very little Mac expertise and we've not been + able to do a successful install of the latest version. We got + close, though. If you've managed it, tell us how and we can update + these docs! + Install Packages ================ @@ -109,10 +114,8 @@ Database Engine Bugzilla supports MySQL, PostgreSQL, Oracle and SQLite as database servers. You only require one of these systems to make use of Bugzilla. MySQL is -most commonly used on Mac OS X. Configure your server according to the -instructions below: - -.. todo:: Has anyone tried anything other than MySQL on Mac OS X? +most commonly used on Mac OS X. (In fact, we have no reports of anyone using +anything else.) Configure your server according to the instructions below: * :ref:`mysql` * :ref:`postgresql` diff --git a/docs/en/rst/maintaining/merging-accounts.rst b/docs/en/rst/installing/merging-accounts.rst similarity index 100% rename from docs/en/rst/maintaining/merging-accounts.rst rename to docs/en/rst/installing/merging-accounts.rst diff --git a/docs/en/rst/installing/migrating-from-1.inc.rst b/docs/en/rst/installing/migrating-from-1.inc.rst new file mode 100644 index 0000000000..d834a8605d --- /dev/null +++ b/docs/en/rst/installing/migrating-from-1.inc.rst @@ -0,0 +1,7 @@ +.. This file is included in multiple places, so can't have labels as they + appear as duplicates. + +The procedure to migrate to Git is as follows. The idea is to switch version +control systems without changing the version of Bugzilla you are using, +to minimise the risk of conflict or problems. Any upgrade can then +happen as a separate step. diff --git a/docs/en/rst/upgrading/migrating-from-2.inc.rst b/docs/en/rst/installing/migrating-from-2.inc.rst similarity index 81% rename from docs/en/rst/upgrading/migrating-from-2.inc.rst rename to docs/en/rst/installing/migrating-from-2.inc.rst index 351850ada7..873a9c87da 100644 --- a/docs/en/rst/upgrading/migrating-from-2.inc.rst +++ b/docs/en/rst/installing/migrating-from-2.inc.rst @@ -4,12 +4,19 @@ Download Code from Git ====================== -Download an additional 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 distributions have it; -search your package manager for "git". On Windows or Mac OS X, you can +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 +:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for +:code:`BUGZILLA_VERSION`. + +Then, you need to download an additional copy of your *current* version of +Bugzilla from the git repository, and place it in a separate directory +alongside your existing Bugzilla installation (which we will assume is in a +directory called :file:`bugzilla`). + +To do this, you will need a copy of the :command:`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 `_. Once git is installed, run these commands to pull a copy of Bugzilla: @@ -24,6 +31,9 @@ Replace $VERSION with the three-digit version number of your current Bugzilla, e.g. "4.2.2". (If the the final digit would have been a 0, omit it - so use "4.4" for the first release in the 4.4 series.) +You will get a message about a 'detached HEAD'. Don't worry; your head is +still firmly attached to your shoulders. + Save Any Local Customizations ============================= @@ -33,8 +43,9 @@ Go into your original Bugzilla directory and run this command: 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, +then :file:`patch.diff` will have significant content. You will want to keep a copy +of those changes by keeping a copy of this file and any files referenced in it +by "Only in" lines. If the file has zero size or only insignificant content, you haven't made any local customizations of this sort. Shut Down Bugzilla diff --git a/docs/en/rst/installing/migrating-from-a-tarball.rst b/docs/en/rst/installing/migrating-from-a-tarball.rst new file mode 100644 index 0000000000..852cb8dbe7 --- /dev/null +++ b/docs/en/rst/installing/migrating-from-a-tarball.rst @@ -0,0 +1,15 @@ +.. _migrating-from-a-tarball: + +Migrating from a Tarball +######################## + +.. |diffcommand| replace:: :command:`diff -ru -x data -x lib -x docs -x .git -x CVS -x .cvsignore -x .bzr -x .bzrignore -x .bzrrev ../bugzilla-new . > ../patch.diff` + +.. |extstatusinfo| replace:: Copy across any subdirectories which do not exist + in your new install. + +The procedure to migrate to Git is as follows. The idea is to switch without +changing the version of Bugzilla you are using, to minimise the risk of +conflict or problems. Any upgrade can then happen as a separate step. + +.. include:: migrating-from-2.inc.rst diff --git a/docs/en/rst/upgrading/migrating-from-bzr.rst b/docs/en/rst/installing/migrating-from-bzr.rst similarity index 100% rename from docs/en/rst/upgrading/migrating-from-bzr.rst rename to docs/en/rst/installing/migrating-from-bzr.rst diff --git a/docs/en/rst/upgrading/migrating-from-cvs.rst b/docs/en/rst/installing/migrating-from-cvs.rst similarity index 100% rename from docs/en/rst/upgrading/migrating-from-cvs.rst rename to docs/en/rst/installing/migrating-from-cvs.rst diff --git a/docs/en/rst/installing/multiple-bugzillas.rst b/docs/en/rst/installing/multiple-bugzillas.rst new file mode 100644 index 0000000000..1e2d7951fa --- /dev/null +++ b/docs/en/rst/installing/multiple-bugzillas.rst @@ -0,0 +1,41 @@ +.. _multiple-bz-dbs: + +One Installation, Multiple Instances +#################################### + +This is a somewhat specialist feature; if you don't know whether you need it, +you don't. It is useful to admins who want to run many separate instances of +Bugzilla from a single installed codebase. + +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 bugzilla.example.com + SetEnv PROJECT foo + + +Don't forget to also export this variable before accessing Bugzilla +by other means, such as repeating tasks like those above. diff --git a/docs/en/rst/installing/optional-post-install-config.rst b/docs/en/rst/installing/optional-post-install-config.rst index 4cf744cf8f..f79918d2ac 100644 --- a/docs/en/rst/installing/optional-post-install-config.rst +++ b/docs/en/rst/installing/optional-post-install-config.rst @@ -131,47 +131,3 @@ Download and install Graphviz from the complete path to :file:`dot.exe` in the :param:`webdotbase` parameter, using forward slashes as path separators. E.g. :paramval:`C:/Program Files/ATT/Graphviz/bin/dot.exe`. - -.. _multiple-bz-dbs: - -Running Multiple Bugzillas from a Single Code Installation -========================================================== - -.. todo:: This doesn't really live here. Where does it live? - -This is a somewhat specialist feature; if you don't know whether you need it, -you don't. It is useful to admins who want to run many separate instances of -Bugzilla from a single codebase. - -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 bugzilla.example.com - SetEnv PROJECT foo - - -Don't forget to also export this variable before accessing Bugzilla -by other means, such as repeating tasks like those above. diff --git a/docs/en/rst/installing/quick-start.rst b/docs/en/rst/installing/quick-start.rst index 5ef758f306..220421bcef 100644 --- a/docs/en/rst/installing/quick-start.rst +++ b/docs/en/rst/installing/quick-start.rst @@ -1,11 +1,11 @@ .. _quick-start: -Quick Start (Ubuntu 14.04 LTS) -############################## +Quick Start (Ubuntu Linux 14.04) +################################ This quick start guide makes installing Bugzilla as simple as possible for those who are able to choose their environment. It creates a system using -Ubuntu 14.04 LTS, Apache and MySQL, and installs Bugzilla as the default +Ubuntu Linux 14.04 LTS, Apache and MySQL, and installs Bugzilla as the default home page. It requires a little familiarity with Linux and the command line. Obtain Your Hardware @@ -166,7 +166,8 @@ Test Server :command:`./testserver.pl http://localhost/` -All the tests should pass. +All the tests should pass. You will get warnings about deprecation from +the ``Chart::Base`` Perl module; just ignore those. .. todo:: Chart::Base gives confusing deprecation warnings :-| https://rt.cpan.org/Public/Bug/Display.html?id=79658 , unfixed for diff --git a/docs/en/rst/maintaining/sanity-check.rst b/docs/en/rst/installing/sanity-check.rst similarity index 100% rename from docs/en/rst/maintaining/sanity-check.rst rename to docs/en/rst/installing/sanity-check.rst diff --git a/docs/en/rst/upgrading/upgrading-customizations.rst b/docs/en/rst/installing/upgrading-customizations.rst similarity index 100% rename from docs/en/rst/upgrading/upgrading-customizations.rst rename to docs/en/rst/installing/upgrading-customizations.rst diff --git a/docs/en/rst/upgrading/upgrading-with-1.inc.rst b/docs/en/rst/installing/upgrading-with-1.inc.rst similarity index 100% rename from docs/en/rst/upgrading/upgrading-with-1.inc.rst rename to docs/en/rst/installing/upgrading-with-1.inc.rst diff --git a/docs/en/rst/upgrading/upgrading-with-2.inc.rst b/docs/en/rst/installing/upgrading-with-2.inc.rst similarity index 100% rename from docs/en/rst/upgrading/upgrading-with-2.inc.rst rename to docs/en/rst/installing/upgrading-with-2.inc.rst diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/installing/upgrading-with-a-tarball.rst similarity index 100% rename from docs/en/rst/upgrading/upgrading-with-a-tarball.rst rename to docs/en/rst/installing/upgrading-with-a-tarball.rst diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/installing/upgrading-with-git.rst similarity index 100% rename from docs/en/rst/upgrading/upgrading-with-git.rst rename to docs/en/rst/installing/upgrading-with-git.rst diff --git a/docs/en/rst/upgrading/overview.rst b/docs/en/rst/installing/upgrading.rst similarity index 78% rename from docs/en/rst/upgrading/overview.rst rename to docs/en/rst/installing/upgrading.rst index c23cd07103..f43897fb30 100644 --- a/docs/en/rst/upgrading/overview.rst +++ b/docs/en/rst/installing/upgrading.rst @@ -1,7 +1,7 @@ -.. _upgrading-overview: +.. _upgrading: -Overview -######## +Upgrading +######### 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 @@ -50,3 +50,21 @@ a tarball. See :ref:`upgrading-with-a-tarball`. Whichever path you use, you may need help with :ref:`upgrading-customizations`. + +.. toctree:: + :maxdepth: 1 + + upgrading-with-git + migrating-from-bzr + migrating-from-cvs + migrating-from-a-tarball + upgrading-with-a-tarball + upgrading-customizations + +Bugzilla can automatically notify administrators when new releases are +available if the :param:`upgrade_notification` parameter is set. +Administrators will see these notifications when they access the Bugzilla home +page. Bugzilla will check once per day for new releases. If you are behind a +proxy, you may have to set the :param:`proxy_url` parameter accordingly. If +the proxy requires authentication, use the +:paramval:`http://user:pass@proxy_url/` syntax. diff --git a/docs/en/rst/installing/windows.rst b/docs/en/rst/installing/windows.rst index 49c2a9ea60..30c0b25a2d 100644 --- a/docs/en/rst/installing/windows.rst +++ b/docs/en/rst/installing/windows.rst @@ -4,13 +4,9 @@ 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. However, if -you are still determined to do it, here's how. - -.. note:: ``mod_perl`` doesn't work very well on Windows, so you probably - don't want to use Windows for a large site. - -.. todo:: Is this still true? +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. .. windows-install-perl: diff --git a/docs/en/rst/customizing/writing-extensions.rst b/docs/en/rst/integrating/extensions.rst similarity index 91% rename from docs/en/rst/customizing/writing-extensions.rst rename to docs/en/rst/integrating/extensions.rst index 6dddcc7378..2097909fc3 100644 --- a/docs/en/rst/customizing/writing-extensions.rst +++ b/docs/en/rst/integrating/extensions.rst @@ -1,11 +1,19 @@ -.. _writing-extensions: +.. _extensions: -Writing Extensions -################## +Extensions +########## -See the `Bugzilla Extension +One of the best ways to customize Bugzilla is by using a Bugzilla +Extension. Extensions can modify both the code and UI of Bugzilla in a way +that can be distributed to other Bugzilla users and ported forward to future +versions of Bugzilla with minimal effort. We maintain a +`list of available extensions `_ +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 write your own extension. See the `Bugzilla Extension documentation <../html/api/Bugzilla/Extension.html>`_ for the core -documentation on how to write an Extension. It would make sense to read +documentation on how to do that. It would make sense to read the section on :ref:`templates`. There is also a sample extension in :file:`$BUGZILLA_HOME/extensions/Example/` which gives examples of how to use all the code hooks. diff --git a/docs/en/rst/customizing/faq.rst b/docs/en/rst/integrating/faq.rst similarity index 100% rename from docs/en/rst/customizing/faq.rst rename to docs/en/rst/integrating/faq.rst diff --git a/docs/en/rst/integrating/index.rst b/docs/en/rst/integrating/index.rst index ad1f412c9e..816ffe8e54 100644 --- a/docs/en/rst/integrating/index.rst +++ b/docs/en/rst/integrating/index.rst @@ -1,12 +1,22 @@ +.. highlight:: perl + .. _integrating: -========================= -Integrating with Bugzilla -========================= +=================================== +Integration and Customization Guide +=================================== + +You may find that Bugzilla already does what you want it to do, you just +need to configure it correctly. Read the :ref:`administering` sections +carefully to see if that's the case for you. If not, then this chapter +explains how to use the available mechanisms for integration and customization. .. toctree:: :maxdepth: 2 + faq + languages + skins + templates + extensions apis - tips - diff --git a/docs/en/rst/customizing/languages.rst b/docs/en/rst/integrating/languages.rst similarity index 100% rename from docs/en/rst/customizing/languages.rst rename to docs/en/rst/integrating/languages.rst diff --git a/docs/en/rst/customizing/skins.rst b/docs/en/rst/integrating/skins.rst similarity index 100% rename from docs/en/rst/customizing/skins.rst rename to docs/en/rst/integrating/skins.rst diff --git a/docs/en/rst/customizing/templates.rst b/docs/en/rst/integrating/templates.rst similarity index 99% rename from docs/en/rst/customizing/templates.rst rename to docs/en/rst/integrating/templates.rst index d06f6a9a68..f30b4a8482 100644 --- a/docs/en/rst/customizing/templates.rst +++ b/docs/en/rst/integrating/templates.rst @@ -5,7 +5,7 @@ Templates Bugzilla uses a system of templates to define its user interface. The standard templates can be modified, replaced or overridden. You can also use template -hooks in an :ref:`extension ` to add or modify the +hooks in an :ref:`extension ` to add or modify the behaviour of templates using a stable interface. .. _template-directory: diff --git a/docs/en/rst/integrating/tips.rst b/docs/en/rst/integrating/tips.rst deleted file mode 100644 index 4c0961aa6a..0000000000 --- a/docs/en/rst/integrating/tips.rst +++ /dev/null @@ -1,6 +0,0 @@ -.. _tips: - -Integration Tips -################ - -.. todo:: Do we have any of these? diff --git a/docs/en/rst/maintaining/index.rst b/docs/en/rst/maintaining/index.rst deleted file mode 100644 index e92c8c5552..0000000000 --- a/docs/en/rst/maintaining/index.rst +++ /dev/null @@ -1,13 +0,0 @@ -.. _maintaining: - -==================== -Maintaining Bugzilla -==================== - -.. toctree:: - :maxdepth: 2 - - upgrades - backups - sanity-check - merging-accounts diff --git a/docs/en/rst/maintaining/upgrades.rst b/docs/en/rst/maintaining/upgrades.rst deleted file mode 100644 index 99af808f7d..0000000000 --- a/docs/en/rst/maintaining/upgrades.rst +++ /dev/null @@ -1,14 +0,0 @@ -.. _upgrades: - -Upgrades -######## - -For details on how to upgrade Bugzilla, see the :ref:`upgrading` chapter. - -Bugzilla can automatically notify administrators when new releases are -available if the :param:`upgrade_notification` parameter is set. -Administrators will see these notifications when they access the Bugzilla home -page. Bugzilla will check once per day for new releases. If you are behind a -proxy, you may have to set the :param:`proxy_url` parameter accordingly. If -the proxy requires authentication, use the -:paramval:`http://user:pass@proxy_url/` syntax. diff --git a/docs/en/rst/upgrading/index.rst b/docs/en/rst/upgrading/index.rst deleted file mode 100644 index 138c1d260d..0000000000 --- a/docs/en/rst/upgrading/index.rst +++ /dev/null @@ -1,16 +0,0 @@ -.. _upgrading: - -================== -Upgrading Bugzilla -================== - -.. toctree:: - :maxdepth: 2 - - overview - upgrading-with-git - migrating-from-bzr - migrating-from-cvs - migrating-from-a-tarball - upgrading-with-a-tarball - upgrading-customizations diff --git a/docs/en/rst/upgrading/migrating-from-1.inc.rst b/docs/en/rst/upgrading/migrating-from-1.inc.rst deleted file mode 100644 index 481d1b2afc..0000000000 --- a/docs/en/rst/upgrading/migrating-from-1.inc.rst +++ /dev/null @@ -1,56 +0,0 @@ -.. This file is included in multiple places, so can't have labels as they - appear as duplicates. - -The procedure to migrate to Git is as follows. The idea is to switch version -control systems without changing the 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 Bugzilla To The Latest Point Release -=========================================== - -It is recommended that you switch to Git while using the latest -point release for your version, so if you aren't running that, you may -want to do a minor upgrade first. - -.. todo:: Is this actually necessary? It adds several extra steps. What are we - trying to avoid here? If we do have to do it, can we avoid them - having to work out the latest point release manually? And do the - bzr and CVS update commands take the full version number including - the third digit, or do they just take major and minor? We need to - make sure all commands operate on the same version number style, - and that it's clearly explained. - -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 -:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for -:code:`BUGZILLA_VERSION`. - -Then, you need to find out what the latest point release for that major -version of Bugzilla is. The -`Bugzilla download page `_ -should tell you that for supported versions. For versions out of support, here -is a list of the final point releases: - -* 3.6.13 -* 3.4.14 -* 3.2.10 -* 3.0.11 -* 2.22.7 -* 2.20.7 -* 2.18.6 -* 2.16.11 -* 2.14.5 - -If you are not currently running the latest point release, you should use the -following update command: - -|updatecommand| - -Where you replace $VERSION by the version number of the latest point release. -Then run checksetup to upgrade your database: - -:command:`./checksetup.pl` - -You should then test your Bugzilla carefully, or just use it for a day or two, -to make sure it's all still working fine. diff --git a/docs/en/rst/upgrading/migrating-from-a-tarball.rst b/docs/en/rst/upgrading/migrating-from-a-tarball.rst deleted file mode 100644 index 9d075746d1..0000000000 --- a/docs/en/rst/upgrading/migrating-from-a-tarball.rst +++ /dev/null @@ -1,25 +0,0 @@ -.. _migrating-from-a-tarball: - -Migrating from a Tarball -######################## - -.. todo:: Need to check the diff command in the tarball case using a real - tarball and git checkout - -.. |diffcommand| replace:: :command:`diff -ru -x data -x .git ../bugzilla-new . > patch.diff` -.. |extstatusinfo| replace:: Copy across any subdirectories which do not exist - in your new install. - -The procedure to migrate to Git is as follows. The idea is to switch without -changing the version of Bugzilla you are using, to minimise the risk of -conflict or problems. Any major upgrade can then happen as a separate step. - -Find Your Current Bugzilla 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 -:file:`Bugzilla/Constants.pm` in your Bugzilla directory and search for -:code:`BUGZILLA_VERSION`. - -.. include:: migrating-from-2.inc.rst diff --git a/docs/en/rst/using/finding.rst b/docs/en/rst/using/finding.rst index 9acbd460bd..414e30cbae 100644 --- a/docs/en/rst/using/finding.rst +++ b/docs/en/rst/using/finding.rst @@ -35,6 +35,7 @@ alias. .. todo:: Need to incorporate the full reference, and link it properly from the GUI. https://bugzilla.mozilla.org/page.cgi?id=quicksearch.html + Turn this item into a bug after checkin. Simple Search ============= @@ -101,7 +102,8 @@ Multiple Charts --------------- .. todo:: This needs rewriting for the new UI. - + Turn this item into a bug after checkin. + The terms within a single row of a boolean chart are all constraints on a single piece of data. If you are looking for a bug that has two different people cc'd on it, then you need @@ -247,7 +249,8 @@ Adding and Removing Tags on Bugs ================================ .. todo:: Looks like you can no longer do this from search results; is that right? - + Turn this item into a bug after checkin. + You can add and remove tags from individual bugs, which let you find and manage bugs more easily. Tags are per-user and so are only visible and editable by the user who created them. You can then run queries using tags as a criteria, diff --git a/docs/en/rst/using/index.rst b/docs/en/rst/using/index.rst index a8777558dd..f336b3729f 100644 --- a/docs/en/rst/using/index.rst +++ b/docs/en/rst/using/index.rst @@ -1,8 +1,8 @@ .. _using: -============== -Using Bugzilla -============== +========== +User Guide +========== .. toctree:: :maxdepth: 2 diff --git a/docs/en/rst/using/tips.rst b/docs/en/rst/using/tips.rst index ef7ce6d4a9..a481492759 100644 --- a/docs/en/rst/using/tips.rst +++ b/docs/en/rst/using/tips.rst @@ -83,7 +83,8 @@ next to the Markdown checkbox for new comments. Bugzilla because the docs aren't always on a Bugzilla (e.g. when they are on ReadTheDocs). Best solution is to port the Markdown guide to ReST. - + Turn this item into a bug after checkin. + 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