From: Gervase Markham Date: Mon, 15 Sep 2014 15:08:17 +0000 (+0800) Subject: WIP; also merge from trunk up to and including bug 1066184. X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=a0646ff7d1452e86361aec4e463f0d9ec2135bfe;p=thirdparty%2Fbugzilla.git WIP; also merge from trunk up to and including bug 1066184. --- diff --git a/docs/en/rst/about/document-conventions.rst b/docs/en/rst/about/document-conventions.rst index 350b35cb38..507e704911 100644 --- a/docs/en/rst/about/document-conventions.rst +++ b/docs/en/rst/about/document-conventions.rst @@ -23,10 +23,14 @@ A sample of code is illustrated like this: Second Line of Code ... -This documentation is maintained in reStructured Text format using the -`Sphinx `_ documentation system. -Changes are best submitted as diffs, attached -to a bug filed in the `Bugzilla Documentation +This documentation is maintained in +`reStructured Text +`_ format using +the `Sphinx `_ documentation system. It has +recently been rewritten, so undoubtedly has bugs. Please file bugs on it in +the `Bugzilla Documentation `_ -component. There is a :ref:`Style Guide ` to help you. +component. If you want to make a patch, that would be wonderful. Changes are +best submitted as diffs, attached to a bug. There is a +:ref:`Style Guide ` to help you write any new text and markup. diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst index 30e1851ad5..d1dc0aa1c2 100644 --- a/docs/en/rst/administering/parameters.rst +++ b/docs/en/rst/administering/parameters.rst @@ -472,7 +472,7 @@ user_verify_class (in the Authentication section) well, you may otherwise not be able to log back in to Bugzilla once you log out. If this happens to you, you will need to manually edit - :file:`data/params` and set :param:`user_verify_class` to + :file:`data/params.json` and set :param:`user_verify_class` to :paramval:`DB`. LDAPserver @@ -548,7 +548,7 @@ user_verify_class (in the Authentication section) well, you may otherwise not be able to log back in to Bugzilla once you log out. If this happens to you, you will need to manually edit - :file:`data/params` and set :param:`user_verify_class` to + :file:`data/params.json` and set :param:`user_verify_class` to :paramval:`DB`. RADIUS_server diff --git a/docs/en/rst/conf.py b/docs/en/rst/conf.py index bcbcc16572..a298f2ced9 100644 --- a/docs/en/rst/conf.py +++ b/docs/en/rst/conf.py @@ -158,7 +158,7 @@ html_use_smartypants = False #html_domain_indices = True # If false, no index is generated. -#html_use_index = True +html_use_index = False # If true, the index is split into individual pages for each letter. #html_split_index = False diff --git a/docs/en/rst/customizing/extensions.rst b/docs/en/rst/customizing/extensions.rst index 24058127e3..a12f86c739 100644 --- a/docs/en/rst/customizing/extensions.rst +++ b/docs/en/rst/customizing/extensions.rst @@ -11,5 +11,6 @@ effort. We maintain a `list of available extensions `_ -on our wiki. You would need to +written by other people on our wiki. You would need to make sure that the extension in question works with your version of Bugzilla. +Or you can look into :ref:`writing your own extension `. diff --git a/docs/en/rst/customizing/languages.rst b/docs/en/rst/customizing/languages.rst index 9f62605757..8360c60648 100644 --- a/docs/en/rst/customizing/languages.rst +++ b/docs/en/rst/customizing/languages.rst @@ -1,7 +1,8 @@ Languages ========= -Bugzilla's templates can be localized, although it's a big job. If you have +Bugzilla's templates can be localized, although it's a `big job +`_. If you have a localized set of templates for your version of Bugzilla, Bugzilla can support multiple languages at once. In that case, Bugzilla honours the user's ``Accept-Language`` HTTP header when deciding which language to serve. @@ -9,4 +10,7 @@ support multiple languages at once. In that case, Bugzilla honours the user's Many language templates can be obtained from `the localization section of the Bugzilla website `_. Instructions -for submitting new languages are also available from that location. +for submitting new languages are also available from that location. There's +also a `list of localization teams +`_; you might +want to contact someone to ask about the status of their localization. diff --git a/docs/en/rst/customizing/templates.rst b/docs/en/rst/customizing/templates.rst index 85a6cf5bd3..607525a223 100644 --- a/docs/en/rst/customizing/templates.rst +++ b/docs/en/rst/customizing/templates.rst @@ -35,38 +35,51 @@ Choosing a Customization Method =============================== If you want to edit Bugzilla's templates, the first decision -you must make is how you want to go about doing so. There are two +you must make is how you want to go about doing so. There are three choices, and which you use depends mainly on the scope of your modifications, and the method you plan to use to upgrade Bugzilla. -The first method of making customizations is to directly edit the -templates found in :file:`template/en/default`. -This is probably the best way for minor changes, because when you upgrade -Bugzilla, either the source code management system or the :file:`patch` tool -will merge your changes into the new version for you. - -On the downside, if the merge fails then Bugzilla will not work properly until -you have fixed the problem and re-integrated your code. - -The second method is to copy the templates to be modified -into a mirrored directory structure under -:file:`template/en/custom`. Templates in this -directory structure automatically override any identically-named -and identically-located templates in the -:file:`template/en/default` directory. (The :file:`custom` directory does not -exist by default and must be created if you want to use it.) - -The second method of customization should be used if you are going to make -major changes, because it is guaranteed that the contents of this directory -will not be touched during an upgrade, and you can then decide whether +#. You can directly edit the templates found in :file:`template/en/default`. + This is probably the best way for minor changes, because when you upgrade + Bugzilla, either the source code management system or the :file:`patch` tool + will merge your changes into the new version for you. + + On the downside, if the merge fails then Bugzilla will not work properly until + you have fixed the problem and re-integrated your code. + +#. You can copy the templates to be modified into a mirrored directory + structure under :file:`template/en/custom`. Templates in this + directory structure automatically override any identically-named + and identically-located templates in the + :file:`template/en/default` directory. (The :file:`custom` directory does + not exist by default and must be created if you want to use it.) + +#. You can use the hooks built into many of the templates to add or modify + the UI from an :ref:`extension`. Hooks generally don't go away and have + a stable interface. + +The third method is the best if there are hooks in the appropriate places. +Unlike code hooks, there is no requirement to document template hooks, so +you just have to open up the template and see (search for 'Hook.process'). + +If there are no hooks available, then the second method of customization +should be used if you are going to make major changes, because it is +guaranteed that the contents of the :file:`custom` directory will not be +touched during an upgrade, and you can then decide whether to continue using your own templates, or make the effort to merge your -changes into the new versions by hand. +changes into the new versions by hand. It's also good for entirely new files, +and for a few files like :file:`bug/create/user-message.html.tmpl` which +are designed to be entirely replaced. -Using this method, your installation may break if incompatible -changes are made to the template interface. Such changes should +Using the second method, your installation may break if incompatible +changes are made to the template interface. Such changes should be documented in the release notes, provided you are using a stable release of Bugzilla, so you should be able to see them coming. +For minor changes, the convenience of the first method is hard to beat. You +can see what you've changed using :command:`git diff`, which you can't if +you fork the file into the :file:`custom` directory. + .. _template-edit: How To Edit Templates @@ -77,8 +90,6 @@ How To Edit Templates sections of the `Developers' Guide `_. - XXX Is this still there? - Bugzilla uses a templating system called Template Toolkit. The syntax of the TT language is beyond the scope of this guide. It's reasonably easy to pick up by looking at the current @@ -146,7 +157,7 @@ constant. If your content type is not there, add it. Remember the three- or four-letter tag assigned to your content type. This tag will be part of the template filename. -.. note:: After adding or changing a content type, it's suitable to +.. note:: After adding or changing a content type, you need to edit :file:`Bugzilla/Constants.pm` in order to reflect the changes. Also, the file should be kept up to date after an upgrade if content types have been customized in the past. diff --git a/docs/en/rst/customizing/writing-extensions.rst b/docs/en/rst/customizing/writing-extensions.rst index 9421eb53f5..c2796bb3fa 100644 --- a/docs/en/rst/customizing/writing-extensions.rst +++ b/docs/en/rst/customizing/writing-extensions.rst @@ -4,7 +4,107 @@ Writing Extensions ################## See the `Bugzilla Extension -documentation <../html/api/Bugzilla/Extension.html>`_ for information on how -to write an Extension. +documentation <../html/api/Bugzilla/Extension.html>`_ for the core +documentation on how to write an Extension. We also have some additional +tips and tricks here. -XXX Also https://wiki.mozilla.org/Bugzilla:Extension_Notes +XXX These came from the wiki. Should they actually be integrated into the +POD, or should some of the POD come here, or something else? + +Checking Syntax +=============== + +It's not immediately obvious how to check the syntax of your extension's +modules. Running checksetup.pl might do some of it, but the errors aren't +necessarily massively informative. + +:command:`perl -Mlib=lib -MBugzilla -e 'BEGIN { Bugzilla->extensions; } use Bugzilla::Extension::ExtensionName::Class;'` + +(run from ``$BUGZILLA_HOME``) will do the trick. + +Adding New Fields To Bugs +========================= + +To add new fields to a bug, you need to do the following: + +* Add an ``install_update_db`` hook to add the fields by calling + ``Bugzilla::Field->create`` (only if the field doesn't already exist). + Here's what it might look like for a single field: + + .. code-block:: perl + + my $field = new Bugzilla::Field({ name => $name }); + return if $field; + + $field = Bugzilla::Field->create({ + name => $name, + description => $description, + type => $type, # From list in Constants.pm + enter_bug => 0, + buglist => 0, + custom => 1, + }); + +* Push the name of the field onto the relevant arrays in the ``bug_columns`` + and ``bug_fields`` hooks. + +* If you want direct accessors, or other functions on the object, you need to + add a BEGIN block to your Extension.pm: + + .. code-block:: perl + + BEGIN { + *Bugzilla::Bug::is_foopy = \&_bug_is_foopy; + } + + ... + + sub _bug_is_foopy { + return $_[0]->{'is_foopy'}; + } + +* You don't have to change ``Bugzilla/DB/Schema.pm``. + +Adding New Fields To Other Things +================================= + +If you are adding the new fields to an object other than a bug, you need to +go a bit lower-level. + +* In ``install_update_db``, use ``bz_add_column`` instead + +* Push on the columns in ``object_columns`` and ``object_update_columns`` + instead of ``bug_columns``. + +* Add validators for the values in ``object_validators`` + +The process for adding accessor functions is the same. + +Adding Configuration Panels +=========================== + +As well as using the ``config_add_panels`` hook, you will need a template to +define the UI strings for the panel. See the templates in +:file:`template/en/default/admin/params` for examples, and put your own +template in :file:`template/en/default/admin/params` in your extension's +directory. + +Adding User Preferences +======================= + +To add a new user preference: + +* Call ``add_setting('setting_name', ['some_option', 'another_option'], + 'some_option')`` in the ``install_before_final_checks`` hook. (The last + parameter is the name of the option which should be the default.) + +* Add descriptions for the identifiers for your setting and choices + (setting_name, some_option etc.) to the hash defined in + :file:`global/setting-descs.none.tmpl`. Do this in a hook: + :file:`hook/global/setting-descs-settings.none.tmpl`. Your code can see the + hash variable; just set more members in it. + +* To change behaviour based on the setting, reference it in templates using + ``[% user.settings.setting_name.value %]``. Reference it in code using + ``$user->settings->{'setting_name'}->{'value'}``. The value will be one of + the option tag names (e.g. some_option). diff --git a/docs/en/rst/installing/apache.rst b/docs/en/rst/installing/apache.rst index b276c2e543..d0351c429a 100644 --- a/docs/en/rst/installing/apache.rst +++ b/docs/en/rst/installing/apache.rst @@ -8,6 +8,33 @@ default) and mod_perl. mod_perl is faster but takes more resources. You should probably only consider mod_perl if your Bugzilla is going to be heavily used. +These instructions require editing the Apache configuration file. +In Fedora and Red Hat Linux, this file is found as +:file:`/etc/httpd/conf/httpd.conf`. +In Ubuntu and Debian, it is :file:`/etc/apache2/apache2.conf`. + +Securing Apache +=============== + +When external systems interact with Bugzilla via webservices +(REST/XMLRPC/JSONRPC) they include the user's credentials as part of the URL +(query-string). Therefore, to avoid storing passwords in clear text on the +server we recommend configuring Apache to not include the query-string in its +log files. + +#. Edit the Apache configuration file (see above). + +#. Find the following line in the above mentioned file, which defines the + logging format for ``vhost_combined``: + + .. code-block:: apache + + LogFormat "%v:%p %h %l %u %t \"%r\" %>s %O \"%{Referer}i\" \"%{User-Agent}i\"" vhost_combined + +#. Replace ``%r`` with ``%m %U``. + +#. Restart Apache. + .. _apache-mod_cgi: Apache with mod_cgi @@ -18,9 +45,7 @@ mod_cgi, do the following: XXX Shouldn't we be using sites-available/sites-enabled here? -#. Load :file:`httpd.conf` in your editor. - In Fedora and Red Hat Linux, this file is found in - :file:`/etc/httpd/conf`. +#. Edit the Apache configuration file (see above). #. Apache uses ```` directives to permit fine-grained permission setting. Add the diff --git a/docs/en/rst/installing/iis.rst b/docs/en/rst/installing/iis.rst index c20597f178..82f3da1eeb 100644 --- a/docs/en/rst/installing/iis.rst +++ b/docs/en/rst/installing/iis.rst @@ -64,3 +64,5 @@ Also, and this can't be stressed enough, make sure that files such as :file:`localconfig` and your :file:`data` directory are secured as described in :ref:`security-webserver-access`. + +XXX See also https://wiki.mozilla.org/Installing_under_IIS_7.5 diff --git a/docs/en/rst/installing/linux.rst b/docs/en/rst/installing/linux.rst index 6b5e1a11d4..47907e405c 100644 --- a/docs/en/rst/installing/linux.rst +++ b/docs/en/rst/installing/linux.rst @@ -25,9 +25,43 @@ Install Packages Use your distribution's package manager to install Perl, your preferred database engine (MySQL if in doubt), and a webserver (Apache if in doubt). -XXX Package lists for specific distros - -.. _install-perl: +The commands below will install those things and some of Bugzilla's other +prerequisites as well. If you find a package doesn't install or the name +is not found, just remove it from the list and reissue the command. + +Fedora and Red Hat +------------------ + +:command:`yum install httpd mysql-server mod_perl mod_perl-devel httpd-devel +graphviz patchutils gcc perl-DateTime perl-Template-Toolkit perl-Email-Send +perl-Email-MIME perl-GD perl-Chart perl-Template-GD perl-GDGraph +perl-GDTextUtil perl-PatchReader perl-MIME-tools perl-LDAP perl-Authen-SASL +perl-RadiusPerl perl-SOAP-Lite perl-JSON-RPC perl-JSON-XS perl-Test-Taint +perl-HTML-Scrubber perl-Email-MIME-Attachment-Stripper perl-Email-Reply +perl-TheSchwartz perl-Daemon-Generic perl-Math-Random-Secure perl-YAML +perl-Class-Inspector` + +If you are running RHEL6, you will have to enable the "RHEL Server Optional" +channel in RHN to get some of those packages. + +Ubuntu and Debian +----------------- + +:command:`apt-get install git nano` + +:command:`apt-get install apache2 mysql-server libappconfig-perl +libdate-calc-perl libtemplate-perl libmime-perl build-essential +libdatetime-timezone-perl libdatetime-perl libemail-send-perl +libemail-mime-perl libemail-mime-modifier-perl libdbi-perl libdbd-mysql-perl +libcgi-pm-perl libmath-random-isaac-perl libmath-random-isaac-xs-perl +apache2-mpm-prefork libapache2-mod-perl2 libapache2-mod-perl2-dev +libchart-perl libxml-perl libxml-twig-perl perlmagick libgd-graph-perl +libtemplate-plugin-gd-perl libsoap-lite-perl libhtml-scrubber-perl +libjson-rpc-perl libdaemon-generic-perl libtheschwartz-perl +libtest-taint-perl libauthen-radius-perl libfile-slurp-perl +libencode-detect-perl libmodule-build-perl libnet-ldap-perl +libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl +libhtml-formattext-withlinks-perl libgd-dev lynx-cur` Perl ==== diff --git a/docs/en/rst/installing/moving.rst b/docs/en/rst/installing/moving.rst index c6bc8440eb..3e5f1f33df 100644 --- a/docs/en/rst/installing/moving.rst +++ b/docs/en/rst/installing/moving.rst @@ -38,8 +38,8 @@ things should still work. appropriate variables in :file:`localconfig`. 6. If the new URL to your new Bugzilla installation is different from the old - one, update the :param:`urlbase` parameter in :file:`data/params` using - a text editor. + one, update the :param:`urlbase` parameter in :file:`data/params.json` + using a text editor. 7. Copy the database backup file :file:`bugzilla-backup.sql` file from your old server to the new one. diff --git a/docs/en/rst/style.rst b/docs/en/rst/style.rst index 23a35d3846..8975a0e145 100644 --- a/docs/en/rst/style.rst +++ b/docs/en/rst/style.rst @@ -10,8 +10,10 @@ The Bugzilla documentation uses `reStructured Text (reST) `_, as extended by our documentation compilation tool, `Sphinx `_. This document is a reST document for -demonstration purposes. When you build the docs, it gets built (at least in -the HTML version) as a standalone file, although it isn't as readable in that +demonstration purposes. To learn from it, you need to read it in reST form. + +When you build the docs, this document gets built (at least in +the HTML version) as a standalone file, although it isn't as useful in that form because some of the directives discussed are invisible or change when rendered. @@ -74,14 +76,18 @@ this: .. code-block:: perl - # This is some Perl code - print "Hello"; + # This is some Perl code + print "Hello"; There is a `list of all available lexer names `_ available. We currently use ``console``, ``perl``, and ``sql``. ``none`` is also a valid value. +Use 4-space indentation, except where a different value is better so that +things line up. So normally two spaces for bulleted lists, and 3 spaces +for .. blocks. + Inline Directives ################# diff --git a/docs/en/rst/upgrading/overview.rst b/docs/en/rst/upgrading/overview.rst index 7e6511b80b..ad081aed3e 100644 --- a/docs/en/rst/upgrading/overview.rst +++ b/docs/en/rst/upgrading/overview.rst @@ -6,6 +6,13 @@ Overview You can upgrade Bugzilla from any version to any later version in one go - there is no need to pass through intermediate versions unless you are changing the method by which you obtain the code along the way. + +.. warning:: Upgrading is a one-way process. You cannot "downgrade" an + upgraded Bugzilla. If you wish to revert to the old Bugzilla + version for any reason, you will have to restore your system + from a backup. Those with critical data or large installations may wish + to trial the upgrade on a development server first, using a copy of the + production data and configuration. Bugzilla uses the Git version control system to store its code. A modern Bugzilla installation consists of a checkout of a stable version of the code from our @@ -39,6 +46,3 @@ following subdirectories in your root Bugzilla directory: It is also possible, particularly if your server machine does not have and cannot be configured to have access to the public internet, to upgrade using a tarball. See :ref:`upgrading-with-a-tarball`. - -Before performing any upgrade, it's a good idea to :ref:`back up ` -both your Bugzilla directory and your database. diff --git a/docs/en/rst/upgrading/upgrading-from-1.rst b/docs/en/rst/upgrading/upgrading-from-1.rst index 08dae9953a..37cb7f8b03 100644 --- a/docs/en/rst/upgrading/upgrading-from-1.rst +++ b/docs/en/rst/upgrading/upgrading-from-1.rst @@ -6,9 +6,8 @@ happen as a separate step. Update Bugzilla To The Latest Point Release =========================================== -It is recommended that you switch while using the latest -point release for your major version. You can update to the latest point -release using bzr. +It is recommended that you switch to Git while using the latest +point release for your major version. First, you need to find what version of Bugzilla you are using. It should be in the top right corner of the front page but, if not, open the file @@ -25,10 +24,6 @@ is a list of the final point releases: * 3.4.14 * 3.2.10 * 3.0.11 - -XXX Do we need below here? Are these versions in bzr? Will anyone be running -them from a bzr install? - * 2.22.7 * 2.20.7 * 2.18.6 @@ -57,7 +52,7 @@ Download a copy of your current version of Bugzilla from the git repository into a separate directory alongside your existing Bugzilla installation (which we will assume is in a directory called :file:`bugzilla`). -You will need a copy of the git program. All Linux installations have it; +You will need a copy of the git program. All Linux distributions have it; search your package manager for "git". On Windows or Mac OS X, you can `download the official build `_. diff --git a/docs/en/rst/upgrading/upgrading-from-2.rst b/docs/en/rst/upgrading/upgrading-from-2.rst index cc4721f96d..ebe8c84f9c 100644 --- a/docs/en/rst/upgrading/upgrading-from-2.rst +++ b/docs/en/rst/upgrading/upgrading-from-2.rst @@ -9,7 +9,7 @@ If you have made customizations to your Bugzilla, and you made them by changing the Bugzilla code itself (rather than using the Extension system), then :file:`patch.diff` will have non-zero size. You will want to keep a copy of those changes by keeping a copy of this file. If the file has zero size, -you haven't made any local customizations. +you haven't made any local customizations of this sort. Shut Down Bugzilla ================== @@ -33,13 +33,12 @@ of Bugzilla into the corresponding directory in :file:`bugzilla-new/`: lib/ data/ + template/en/custom (may or may not exist) -You also need to copy an extensions you have written or installed, which are -in the :file:`extensions/` directory. +You also need to copy any extensions you have written or installed, which are +in the :file:`extensions/` directory. |extstatusinfo| -|extstatusinfo| - -Then, copy the following file from your current installation of Bugzilla +Lastly, copy the following file from your current installation of Bugzilla into the corresponding place in :file:`bugzilla-new/`: .. code-block:: none diff --git a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst index 132b82bd7b..1a9c5d97bf 100644 --- a/docs/en/rst/upgrading/upgrading-with-a-tarball.rst +++ b/docs/en/rst/upgrading/upgrading-with-a-tarball.rst @@ -3,9 +3,9 @@ Upgrading with a Tarball ######################## -If you are unable (or unwilling) to use Git, another option that's -always available is to obtain a tarball of the latest version from our -website and upgrade your Bugzilla installation from that. +If you are unable (or unwilling) to use Git, another option is to obtain a +tarball of the latest version from our website and upgrade your Bugzilla +installation using that. Download Bugzilla ================= diff --git a/docs/en/rst/upgrading/upgrading-with-git.rst b/docs/en/rst/upgrading/upgrading-with-git.rst index e52d23bf4d..8221beaa3f 100644 --- a/docs/en/rst/upgrading/upgrading-with-git.rst +++ b/docs/en/rst/upgrading/upgrading-with-git.rst @@ -9,16 +9,6 @@ intermediate steps. There is a script named :file:`checksetup.pl` included with Bugzilla that will automatically do all of the database migration for you. -.. warning:: Upgrading is a one-way process. You cannot "downgrade" an - upgraded Bugzilla. If you wish to revert to the old Bugzilla - version for any reason, you will have to restore your database - from a backup. Those with critical data or large installations may wish - to trial the upgrade on a development server first, using a copy of the - production data and configuration. - -In the commands below, ``$BUGZILLA_HOME`` represents the directory -in which Bugzilla is installed. - .. _upgrade-before: Before You Upgrade @@ -30,21 +20,18 @@ steps to take: #. Read the `Release Notes `_ of the version you're upgrading to and all intermediate versions, particularly the "Notes for - Upgraders" sections, if present. + Upgraders" sections, if present. They may make you aware of additional + considerations. XXX We need to make these more accessible - they are currently rather hard to find. We could collate them on a single page with no intervening cruft. #. Run the :ref:`sanity-check` on your installation. Attempt to fix all - warnings that the page produces before you go any further, or it's + warnings that the page produces before you start, or it's possible that you may experience problems during your upgrade. -#. Shut down your Bugzilla installation by putting some explanatory text - in the :param:`shutdownhtml` parameter. - -#. Make all necessary :ref:`backups`. - *THIS IS VERY IMPORTANT*. If anything goes wrong during the upgrade, - having a backup allows you to roll back to a known good state. +#. Work out how to :ref:`back up ` your Bugzilla entirely, and + how to restore from a backup if need be. .. _upgrade-modified: @@ -67,20 +54,37 @@ changes at all, however, then upgrading should be approximately the same amount of work regardless of how long it has been since your version was released. -XXX Need more here +You should do the upgrade on a test system with the same configuration and +make sure all your customizations still work. If not, port and test them so +you have them ready for the real thing. + +Starting the Upgrade +==================== + +When you are ready to go: + +#. Shut down your Bugzilla installation by putting some explanatory text + in the :param:`shutdownhtml` parameter. + +#. Make all necessary :ref:`backups`. + *THIS IS VERY IMPORTANT*. If anything goes wrong during the upgrade, + having a backup allows you to roll back to a known good state. .. _upgrade-files: Getting The New Bugzilla ======================== +In the commands below, ``$BUGZILLA_HOME`` represents the directory +in which Bugzilla is installed. + :command:`cd $BUGZILLA_HOME` :command:`git checkout` :command:`git pull` -XXX How to pull latest stable? +XXX What is the best way to pull latest stable? .. _upgrade-database: @@ -109,7 +113,7 @@ Finishing The Upgrade #. Reactivate Bugzilla by clear the text that you put into the :param:`shutdownhtml` parameter. -#. Run a :ref:`sanity-check` on your +#. Run another :ref:`sanity-check` on your upgraded Bugzilla. It is recommended that you fix any problems you see immediately. Failure to do this may mean that Bugzilla - will not work entirely correctly. + may not work entirely correctly. diff --git a/docs/en/rst/using/filing.rst b/docs/en/rst/using/filing.rst index 6d576f2017..aa55b1d87a 100644 --- a/docs/en/rst/using/filing.rst +++ b/docs/en/rst/using/filing.rst @@ -23,14 +23,14 @@ for the bug that bit you. The procedure for filing a bug is as follows: -#. Click the ``New`` link available in the header or footer - of pages, or the ``File a Bug`` link on the home page. +#. Click the :guilabel:`New` link available in the header or footer + of pages, or the :guilabel:`File a Bug` link on the home page. #. First, you have to select the product in which you found a bug. #. You now see a form where you can specify the component (part of the product which is affected by the bug you discovered; if you have - no idea, just select ``General`` if such a component exists), + no idea, just select :guilabel:`General` if such a component exists), the version of the program you were using, the operating system and platform your program is running on and the severity of the bug (if the bug you found crashes the program, it's probably a major or a critical @@ -38,7 +38,7 @@ The procedure for filing a bug is as follows: something you would like to see implemented, then that's an enhancement). #. You also need to provide a short but descriptive summary of the bug you found. - ``My program is crashing all the time`` is a very poor summary + "My program is crashing all the time" is a very poor summary and doesn't help developers at all. Try something more meaningful or your bug will probably be ignored due to a lack of precision. In the Description, give a detailed list of steps to reproduce @@ -67,7 +67,7 @@ The procedure for filing a bug is as follows: should know in order to reproduce the problem, and make sure your description of the problem is explicit and clear enough. When you think your bug report is ready to go, the last step is to - click the ``Submit Bug`` button to add your report into the database. + click the :guilabel:`Submit Bug` button to add your report into the database. .. _cloning-a-bug: @@ -77,7 +77,7 @@ Clone an Existing Bug Bugzilla allows you to 'clone' an existing bug. The newly created bug will inherit most settings from the old bug. This allows you to track similar concerns which require different handling in a new bug. To use this, go to -the bug that you want to clone, then click the ``Clone This Bug`` -link on the bug page. This will take you to the ``Enter Bug`` +the bug that you want to clone, then click the :guilabel:`Clone This Bug` +link on the bug page. This will take you to the :guilabel:`Enter Bug` page that is filled with the values that the old bug has. You can then change the values and/or text if needed. diff --git a/docs/en/rst/using/preferences.rst b/docs/en/rst/using/preferences.rst index efe19ffb88..2c7971f9f0 100644 --- a/docs/en/rst/using/preferences.rst +++ b/docs/en/rst/using/preferences.rst @@ -123,9 +123,20 @@ confirm the change. This helps to prevent account hijacking. API Keys ======== -API Keys allow you to give a "token" to a web service so it can log in to -Bugzilla as you without knowing your password. You can then revoke that token -if you stop using the web service. +API Keys allow you to give a "token" to some external software so it can log +in to the WebService API as you without knowing your password. You can then +revoke that token if you stop using the web service, and you don't need to +change your password everywhere. + +You can create more than one API key if required. Each API key has an optional +description which can help you record what each key is used for. + +On this page, you can unrevoke, revoke and change the description of existing +API keys for your login. A revoked key means that it cannot be used. The +description for purely for your information, and is optional. + +You can also create a new API key by selecting the check box under the 'New +API key' section of the page. .. _permissions: diff --git a/docs/en/rst/using/tips.rst b/docs/en/rst/using/tips.rst index e4385520bf..7a7730d561 100644 --- a/docs/en/rst/using/tips.rst +++ b/docs/en/rst/using/tips.rst @@ -19,8 +19,12 @@ Other strings which get linkified in the obvious manner are: + bug 12345 ++ bugs 123, 456, 789 + + comment 7 ++ comments 1, 2, 3, 4 + + bug 23456, comment 53 + attachment 4321 @@ -59,3 +63,29 @@ If you feel a bug you filed was incorrectly marked as a DUPLICATE of another, please question it in your bug, not the bug it was duped to. Feel free to CC the person who duped it if they are not already CCed. + +.. _markdown: + +Markdown +-------- + +Markdown is a structured plain-text format which lets you write comments that +have more styling than plain text. For example, you may use Markdown for +making a part of your comment look italic or bold in the generated HTML. +Bugzilla supports most of the structures defined by +`standard Markdown `_, +but does NOT support inline images and inline HTML. + +Additionally, three Github Flavored Markdown features are supported. + +* `Multiple underscores in words `_ + +* `strikethrough `_ + +* `fenced code blocks `_ + +To use the Markdown feature, make sure that :guilabel:`Enable Markdown +support for comments` is set to :guilabel:`on` +in your :ref:`user-preferences` and that you also check the :guilabel:`Use +Markdown for this comment` option below the comment box when you want to +submit a new comment which uses Markdown.