#. Enter the details as outlined above.
-.. todo:: This section is pointless; if it's not obvious, we should make it more obvious :-)
-
.. _edit-products:
Editing Products
-.. _flags:
+.. _flags-admin:
Flags
#####
-Flags are a way to attach a specific status to a bug or attachment,
-either ``+`` or ``-``. The meaning of these symbols depends on the text
-the flag itself, but contextually they could mean pass/fail,
-accept/reject, approved/denied, or even a simple yes/no. If your site
-allows requestable flags, then users may set a flag to ``?`` as a
-request to another user that they look at the bug/attachment, and set
-the flag to its correct status.
-
-.. _flags-simpleexample:
-
-A Simple Example
-================
-
-A developer might want to ask their manager,
-``Should we fix this bug before we release version 2.0?``
-They might want to do this for a *lot* of bugs,
-so it would be nice to streamline the process...
-
-In Bugzilla, it would work this way:
-
-#. The Bugzilla administrator creates a flag type called
- ``blocking2.0`` that shows up on all bugs in
- your product.
- It shows up on the ``Show Bug`` screen
- as the text ``blocking2.0`` with a drop-down box next
- to it. The drop-down box contains four values: an empty space,
- ``?``, ``-``, and ``+``.
-
-#. The developer sets the flag to ``?``.
-
-#. The manager sees the ``blocking2.0``
- flag with a ``?`` value.
-
-#. If the manager thinks the feature should go into the product
- before version 2.0 can be released, he sets the flag to
- ``+``. Otherwise, he sets it to ``-``.
-
-#. Now, every Bugzilla user who looks at the bug knows whether or
- not the bug needs to be fixed before release of version 2.0.
-
-.. _flags-about:
-
-About Flags
-===========
-
-.. _flag-values:
-
-Values
-------
-
-Flags can have three values:
-
-``?``
- A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
-
-``-``
- The status has been set negatively. (The question has been answered ``no``.)
-
-``+``
- The status has been set positively.
- (The question has been answered ``yes``.)
-
-Actually, there's a fourth value a flag can have --
-``unset`` -- which shows up as a blank space. This
-just means that nobody has expressed an opinion (or asked
-someone else to express an opinion) about this bug or attachment.
-
-.. _flag-askto:
-
-Using flag requests
-===================
-
-If a flag has been defined as 'requestable', and a user has enough privileges
-to request it (see below), the user can set the flag's status to ``?``.
-This status indicates that someone (a.k.a. ``the requester``) is asking
-someone else to set the flag to either ``+`` or ``-``.
-
-If a flag has been defined as 'specifically requestable',
-a text box will appear next to the flag into which the requester may
-enter a Bugzilla username. That named person (a.k.a. ``the requestee``)
-will receive an email notifying them of the request, and pointing them
-to the bug/attachment in question.
-
-If a flag has *not* been defined as 'specifically requestable',
-then no such text-box will appear. A request to set this flag cannot be made of
-any specific individual, but must be asked ``to the wind``.
-A requester may ``ask the wind`` on any flag simply by leaving the text-box blank.
-
-.. _flag-types:
-
-Two Types of Flags
-==================
-
-Flags can go in two places: on an attachment, or on a bug.
-
-.. _flag-type-attachment:
-
-Attachment Flags
-----------------
-
-Attachment flags are used to ask a question about a specific
-attachment on a bug.
-
-Many Bugzilla installations use this to
-request that one developer ``review`` another
-developer's code before they check it in. They attach the code to
-a bug report, and then set a flag on that attachment called
-``review`` to
-``review?boss@domain.com``.
-boss@domain.com is then notified by email that
-he has to check out that attachment and approve it or deny it.
-
-For a Bugzilla user, attachment flags show up in three places:
-
-#. On the list of attachments in the ``Show Bug``
- screen, you can see the current state of any flags that
- have been set to ?, +, or -. You can see who asked about
- the flag (the requester), and who is being asked (the
- requestee).
-
-#. When you ``Edit`` an attachment, you can
- see any settable flag, along with any flags that have
- already been set. This ``Edit Attachment``
- screen is where you set flags to ?, -, +, or unset them.
-
-#. Requests are listed in the ``Request Queue``, which
- is accessible from the ``My Requests`` link (if you are
- logged in) or ``Requests`` link (if you are logged out)
- visible in the footer of all pages.
-
-.. _flag-type-bug:
-
-Bug Flags
----------
-
-Bug flags are used to set a status on the bug itself. You can
-see Bug Flags in the ``Show Bug`` and ``Requests``
-screens, as described above.
-
-Only users with enough privileges (see below) may set flags on bugs.
-This doesn't necessarily include the assignee, reporter, or users with the
-``editbugs`` permission.
-
-.. _flags-admin:
-
-Administering Flags
-===================
-
-If you have the ``editcomponents`` permission, you can
+If you have the :group:`editcomponents` permission, you can
edit Flag Types from the main administration page. Clicking the
-``Flags`` link will bring you to the ``Administer
-Flag Types`` page. Here, you can select whether you want
+:guilabel:`Flags` link will bring you to the :guilabel:`Administer
+Flag Types` page. Here, you can select whether you want
to create (or edit) a Bug flag, or an Attachment flag.
-No matter which you choose, the interface is the same, so we'll
-just go over it once.
+The two flag types have the same administration interface, and the interface
+for creating a flag and editing a flag have the same set of fields.
.. _flags-edit:
-Editing a Flag
---------------
-
-To edit a flag's properties, just click the flag's name.
-That will take you to the same
-form as described below (:ref:`flags-create`).
-
-.. _flags-create:
-
-Creating a Flag
----------------
-
-When you click on the ``Create a Flag Type for...``
-link, you will be presented with a form. Here is what the fields in
-the form mean:
-
-.. _flags-create-field-name:
+Flag Properties
+===============
Name
-~~~~
-
-This is the name of the flag. This will be displayed
-to Bugzilla users who are looking at or setting the flag.
-The name may contain any valid Unicode characters except commas
-and spaces.
-
-.. _flags-create-field-description:
+ This is the name of the flag. This will be displayed
+ to Bugzilla users who are looking at or setting the flag.
+ The name may contain any valid Unicode characters except commas
+ and spaces.
Description
-~~~~~~~~~~~
-
-The description describes the flag in more detail. It is visible
-in a tooltip when hovering over a flag either in the ``Show Bug``
-or ``Edit Attachment`` pages. This field can be as
-long as you like, and can contain any character you want.
-
-.. _flags-create-field-category:
+ The description describes the flag in more detail. It is visible
+ in a tooltip when hovering over a flag either in the :guilabel:`Show Bug`
+ or :guilabel:`Edit Attachment` pages. This field can be as
+ long as you like, and can contain any character you want.
Category
-~~~~~~~~
-
-Default behaviour for a newly-created flag is to appear on
-products and all components, which is why ``__Any__:__Any__``
-is already entered in the ``Inclusions`` box.
-If this is not your desired behaviour, you must either set some
-exclusions (for products on which you don't want the flag to appear),
-or you must remove ``__Any__:__Any__`` from the Inclusions box
-and define products/components specifically for this flag.
-
-To create an Inclusion, select a Product from the top drop-down box.
-You may also select a specific component from the bottom drop-down box.
-(Setting ``__Any__`` for Product translates to,
-``all the products in this Bugzilla``.
-Selecting ``__Any__`` in the Component field means
-``all components in the selected product.``)
-Selections made, press ``Include``, and your
-Product/Component pairing will show up in the ``Inclusions`` box on the right.
-
-To create an Exclusion, the process is the same; select a Product from the
-top drop-down box, select a specific component if you want one, and press
-``Exclude``. The Product/Component pairing will show up in the
-``Exclusions`` box on the right.
-
-This flag *will* and *can* be set for any
-products/components that appearing in the ``Inclusions`` box
-(or which fall under the appropriate ``__Any__``).
-This flag *will not* appear (and therefore cannot be set) on
-any products appearing in the ``Exclusions`` box.
-*IMPORTANT: Exclusions override inclusions.*
-
-You may select a Product without selecting a specific Component,
-but you can't select a Component without a Product, or to select a
-Component that does not belong to the named Product. If you do so,
-Bugzilla will display an error message, even if all your products
-have a component by that name.
-
-*Example:* Let's say you have a product called
-``Jet Plane`` that has thousands of components. You want
-to be able to ask if a problem should be fixed in the next model of
-plane you release. We'll call the flag ``fixInNext``.
-But, there's one component in ``Jet Plane,``
-called ``Pilot.`` It doesn't make sense to release a
-new pilot, so you don't want to have the flag show up in that component.
-So, you include ``Jet Plane:__Any__`` and you exclude
-``Jet Plane:Pilot``.
-
-.. _flags-create-field-sortkey:
+ You can set a flag to be visible or not visible on any combination of
+ products and components.
+
+ Default behaviour for a newly-created flag is to appear on
+ products and all components, which is why ``__Any__:__Any__``
+ is already entered in the :guilabel:`Inclusions` box.
+ If this is not your desired behaviour, you must either set some
+ exclusions (for products on which you don't want the flag to appear),
+ or you must remove ``__Any__:__Any__`` from the :guilabel:`Inclusions` box
+ and define products/components specifically for this flag.
+
+ To create an Inclusion, select a Product from the top drop-down box.
+ You may also select a specific component from the bottom drop-down box.
+ (Setting ``__Any__`` for Product translates to
+ "all the products in this Bugzilla".
+ Selecting ``__Any__`` in the Component field means
+ "all components in the selected product.")
+ Selections made, press :guilabel:`Include`, and your
+ Product/Component pairing will show up in the :guilabel:`Inclusions` box on the right.
+
+ To create an Exclusion, the process is the same; select a Product from the
+ top drop-down box, select a specific component if you want one, and press
+ :guilabel:`Exclude`. The Product/Component pairing will show up in the
+ :guilabel:`Exclusions` box on the right.
+
+ This flag *will* and *can* be set for any
+ products/components that appearing in the :guilabel:`Inclusions` box
+ (or which fall under the appropriate ``__Any__``).
+ This flag *will not* appear (and therefore cannot be set) on
+ any products appearing in the :guilabel:`Exclusions` box.
+ *IMPORTANT: Exclusions override inclusions.*
+
+ You may select a Product without selecting a specific Component,
+ but you can't select a Component without a Product, or to select a
+ Component that does not belong to the named Product. If you do so,
+ Bugzilla will display an error message, even if all your products
+ have a component by that name.
+
+ *Example:* Let's say you have a product called
+ ``Jet Plane`` that has thousands of components. You want
+ to be able to ask if a problem should be fixed in the next model of
+ plane you release. We'll call the flag ``fixInNext``.
+ But, there's one component in ``Jet Plane,``
+ called ``Pilot.`` It doesn't make sense to release a
+ new pilot, so you don't want to have the flag show up in that component.
+ So, you include ``Jet Plane:__Any__`` and you exclude
+ ``Jet Plane:Pilot``.
Sort Key
-~~~~~~~~
-
-Flags normally show up in alphabetical order. If you want them to
-show up in a different order, you can use this key set the order on each flag.
-Flags with a lower sort key will appear before flags with a higher
-sort key. Flags that have the same sort key will be sorted alphabetically,
-but they will still be after flags with a lower sort key, and before flags
-with a higher sort key.
-
-*Example:* I have AFlag (Sort Key 100), BFlag (Sort Key 10),
-CFlag (Sort Key 10), and DFlag (Sort Key 1). These show up in
-the order: DFlag, BFlag, CFlag, AFlag.
-
-.. _flags-create-field-active:
+ Flags normally show up in alphabetical order. If you want them to
+ show up in a different order, you can use this key set the order on each flag.
+ Flags with a lower sort key will appear before flags with a higher
+ sort key. Flags that have the same sort key will be sorted alphabetically.
Active
-~~~~~~
-
-Sometimes, you might want to keep old flag information in the
-Bugzilla database, but stop users from setting any new flags of this type.
-To do this, uncheck ``active``. Deactivated
-flags will still show up in the UI if they are ?, +, or -, but they
-may only be cleared (unset), and cannot be changed to a new value.
-Once a deactivated flag is cleared, it will completely disappear from a
-bug/attachment, and cannot be set again.
-
-.. _flags-create-field-requestable:
+ Sometimes, you might want to keep old flag information in the
+ Bugzilla database, but stop users from setting any new flags of this type.
+ To do this, uncheck :guilabel:`active`. Deactivated
+ flags will still show up in the UI if they are ``?``, ``+``, or ``-``, but
+ they may only be cleared (unset), and cannot be changed to a new value.
+ Once a deactivated flag is cleared, it will completely disappear from a
+ bug/attachment, and cannot be set again.
Requestable
-~~~~~~~~~~~
-
-New flags are, by default, ``requestable``, meaning that they
-offer users the ``?`` option, as well as ``+``
-and ``-``.
-To remove the ? option, uncheck ``requestable``.
-
-.. _flags-create-field-specific:
+ New flags are, by default, "requestable", meaning that they
+ offer users the ``?`` option, as well as ``+``
+ and ``-``.
+ To remove the ? option, uncheck "requestable".
Specifically Requestable
-~~~~~~~~~~~~~~~~~~~~~~~~
-
-By default this box is checked for new flags, meaning that users may make
-flag requests of specific individuals. Unchecking this box will remove the
-text box next to a flag; if it is still requestable, then requests may
-only be made ``to the wind.`` Removing this after specific
-requests have been made will not remove those requests; that data will
-stay in the database (though it will no longer appear to the user).
-
-.. _flags-create-field-multiplicable:
+ By default this box is checked for new flags, meaning that users may make
+ flag requests of specific individuals. Unchecking this box will remove the
+ text box next to a flag; if it is still requestable, then requests may
+ only be made "to the wind". Removing this after specific
+ requests have been made will not remove those requests; that data will
+ stay in the database (though it will no longer appear to the user).
Multiplicable
-~~~~~~~~~~~~~
-
-Any flag with ``Multiplicable`` set (default for new flags is 'on')
-may be set more than once. After being set once, an unset flag
-of the same type will appear below it with ``addl.`` (short for
-``additional``) before the name. There is no limit to the number of
-times a Multiplicable flags may be set on the same bug/attachment.
-
-.. _flags-create-field-cclist:
+ Any flag with :guilabel:`Multiplicable:guilabel:` set (default for new flags
+ is 'on') may be set more than once. After being set once, an unset flag
+ of the same type will appear below it with "addl." (short for
+ "additional") before the name. There is no limit to the number of
+ times a Multiplicable flags may be set on the same bug/attachment.
CC List
-~~~~~~~
-
-If you want certain users to be notified every time this flag is
-set to ?, -, +, or unset, add them here. This is a comma-separated
-list of email addresses that need not be restricted to Bugzilla usernames.
-
-.. _flags-create-grant-group:
+ If you want certain users to be notified every time this flag is
+ set to ``?``, ``-``, ``+``, or unset, add them here. This is a comma-separated
+ list of email addresses that need not be restricted to Bugzilla usernames.
Grant Group
-~~~~~~~~~~~
-
-When this field is set to some given group, only users in the group
-can set the flag to ``+`` and ``-``. This
-field does not affect who can request or cancel the flag. For that,
-see the ``Request Group`` field below. If this field
-is left blank, all users can set or delete this flag. This field is
-useful for restricting which users can approve or reject requests.
-
-.. _flags-create-request-group:
+ When this field is set to some given group, only users in the group
+ can set the flag to ``+`` and ``-``. This
+ field does not affect who can request or cancel the flag. For that,
+ see the :guilabel:`Request Group` field below. If this field
+ is left blank, all users can set or delete this flag. This field is
+ useful for restricting which users can approve or reject requests.
Request Group
-~~~~~~~~~~~~~
-
-When this field is set to some given group, only users in the group
-can request or cancel this flag. Note that this field has no effect
-if the ``grant group`` field is empty. You can set the
-value of this field to a different group, but both fields have to be
-set to a group for this field to have an effect.
-
-.. COMMENT: flags-create
+ When this field is set to some given group, only users in the group
+ can request or cancel this flag. Note that this field has no effect
+ if the :guilabel:`Grant Group` field is empty. You can set the
+ value of this field to a different group, but both fields have to be
+ set to a group for this field to have an effect.
.. _flags-delete:
Deleting a Flag
----------------
+===============
-When you are at the ``Administer Flag Types`` screen,
+When you are at the :guilabel:`Administer Flag Types` screen,
you will be presented with a list of Bug flags and a list of Attachment
Flags.
-To delete a flag, click on the ``Delete`` link next to
+To delete a flag, click on the :guilabel:`Delete` link next to
the flag description.
.. warning:: Once you delete a flag, it is *gone* from
Everywhere that flag was set, it will disappear,
and you cannot get that data back. If you want to keep flag data,
but don't want anybody to set any new flags or change current flags,
- unset ``active`` in the flag Edit form.
-
-.. COMMENT: flags-admin
-
-.. todo:: We should add a "Uses of Flags" section, here, with examples.
-
-.. COMMENT: flags
-
+ unset :guilabel:`active` in the flag Edit form.
log in, and your name/password will be accepted here (but nowhere
else).
- .. todo:: Is this still true?
+ .. 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
when new products are created. If this is on, the groups will be
used for querying bugs.
- .. todo:: This is spectacularly unclear.
+ .. todo:: This is spectacularly unclear. I have no idea what makeproductgroups
+ does - can someone explain it to me?
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.
otherwise), added to any CC list, or any other such operation. One
possible workaround is the :file:`bugzilla_ldapsync.rb`
script in the :file:`contrib`
- directory. Another possible solution is fixing
- `bug
- 201069 <https://bugzilla.mozilla.org/show_bug.cgi?id=201069>`_.
+ directory. Another possible solution is fixing :bug:`201069`.
Parameters required to use LDAP Authentication:
Set this to the number of days you want to let bugs go
in the CONFIRMED state before notifying people they have
untouched new bugs. If you do not plan to use this feature, simply
- do not set up the whining cron job described in the installation
- instructions, or set this value to "0" (never whine).
-
- .. todo:: link
+ do not set up the :ref:`whining cron job <installation-whining>` described
+ in the installation instructions, or set this value to "0" (never whine).
globalwatchers
This allows you to define specific users who will
This page contains configuration parameters for the CVS server,
Bonsai server and LXR server that Bugzilla will use to enable the
-features of the Patch Viewer. Bonsai is a tool that enables queries
+certain features of the Patch Viewer. Bonsai is a tool that enables queries
to a CVS tree. LXR is a tool that can cross reference and index source
code.
-.. todo:: Does anyone use this stuff any more?
+This page is scheduled to be removed in :bug:`1068494`.
cvsroot
The CVS root that most users of your system will be using for 'cvs diff'. Used in Patch Viewer ('Diff' option on patches) to figure out where patches are rooted even if users did the 'cvs diff' from different places in the directory structure. (NOTE: if your CVS repository is remote and requires a password, you must either ensure the Bugzilla user has done a 'cvs login' or specify the password as part of the CVS root.) Leave this blank if you have no CVS repository.
# Temporary highlighting of TODO items
todo_include_todos = True
+
+extlinks = {'bug': ('https://bugzilla.mozilla.org/show_bug.cgi?id=%s', 'bug ')}
+++ /dev/null
-.. _existing-parameters:
-
-Existing Parameters and Options
-===============================
-
-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.
Extensions
##########
-One of the best ways to customize Bugzilla is by writing a Bugzilla
-Extension. Bugzilla Extensions let you 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.
+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 <https://wiki.mozilla.org/Bugzilla:Addons>`_
--- /dev/null
+.. _customization-faq:
+
+Customization FAQ
+=================
+
+How do I...
+
+...add a new field on a bug?
+ Use :ref:`custom-fields` or, if you just want new form fields on bug entry
+ but don't need Bugzilla to track the field seperately thereafter, you can
+ use a :ref:`custom bug entry form <custom-bug-entry>`.
+
+...change the name of a built-in bug field?
+ :ref:`Edit <templates>` the relevant value in the template
+ :file:`template/en/default/global/field-descs.none.tmpl`.
+
+...use a word other than 'bug' to describe bugs?
+ :ref:`Edit or override <templates>` the appropriate values in the template
+ :file:`template/en/default/global/variables.none.tmpl`.
+
+...call the system something other than 'Bugzilla'?
+ :ref:`Edit or override <templates>` the appropriate value in the template
+ :file:`template/en/default/global/variables.none.tmpl`.
+
+...alter who can change what field when?
+ See :ref:`who-can-change-what`.
+
+.. todo:: Ask Thorsten for his input on what questions are common.
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
- existing-parameters
+ faq
extensions
skins
languages
templates
- who-can-change-what
writing-extensions
Skins
=====
-Bugzilla supports skins. It ships with two - "Classic" and "Dusk". You can
+Bugzilla supports skins - ways of changing the look of the UI without altering
+its underlying structure. It ships with two - "Classic" and "Dusk". You can
find some more listed
`on the wiki <https://wiki.mozilla.org/Bugzilla:Addons#Skins>`_, and there
are a couple more which are part of
case you may need to check that the skin supports the version of Bugzilla
you have.
-To create a new custom skin, you have two choices:
+To create a new custom skin, make a directory that contains all the same CSS
+file names as :file:`skins/standard/`, and put your directory in
+:file:`skins/contrib/`. Then, add your CSS to the appropriate files.
-- Make a single CSS file, and put it in the
- :file:`skins/contrib` directory.
-
-- Make a directory that contains all the same CSS file
- names as :file:`skins/standard/`, and put
- your directory in :file:`skins/contrib/`.
-
-After you put the file or the directory there, make sure to run checksetup.pl
-so that it can reset the file permissions correctly.
+After you put the directory there, make sure to run :file:`checksetup.pl` so
+that it can set the file permissions correctly.
After you have installed the new skin, it will show up as an option in the
-user's General Preferences. If you would like to force a particular skin on all
-users, just select it in the Default Preferences and then uncheck "Enabled" on
-the preference.
+user's :guilabel:`Preferences`, on the :guilabel:`General` tab. If you would
+like to force a particular skin on all users, just select that skin in the
+:guilabel:`Default Preferences` in the :guilabel:`Administration` UI, and
+then uncheck "Enabled" on the preference, so users cannot change it.
Templates
#########
-Bugzilla uses a system of templates to define its user interface. Templates
-can be modified, replaced or overridden. This means that administrators can
-configure the look and feel of Bugzilla without having to edit Perl files or
-facing the nightmare of massive merge conflicts when they upgrade to a newer
-version in the future.
+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 <writing-extensions>` to add or modify the
+behaviour of templates using a stable interface.
.. _template-directory:
modifications, and the method you plan to use to upgrade Bugzilla.
#. 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
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').
+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. 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.
+to revert to the standard templates, continue using yours, or make the effort
+to merge your 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 the second method, your user interface may break if incompatible
+changes are made to the template interface. Templates do change regularly
+and so interface changes are not individually documented, and you would
+need to work out what had changed and adapt your template accordingly.
-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. When
+you upgrade Bugzilla, :command:`git` 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.
-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.
+Also, 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:
`Developers' Guide <http://www.bugzilla.org/docs/developer.html>`_.
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
-templates; or, you can read the manual, available on the
-`Template Toolkit home
-page <http://www.template-toolkit.org>`_.
+language is beyond the scope of this guide. It's reasonably easy to pick up by
+looking at the current templates; or, you can read the manual, available on
+the `Template Toolkit home page <http://www.template-toolkit.org>`_.
One thing you should take particular care about is the need
to properly HTML filter data that has been passed into the template.
This means that if the data can possibly contain special HTML characters
-such as <, and the data was not intended to be HTML, they need to be
-converted to entity form, i.e. <. You use the 'html' filter in the
-Template Toolkit to do this (or the 'uri' filter to encode special
+such as ``<``, and the data was not intended to be HTML, they need to be
+converted to entity form, i.e. ``<``. You use the ``html`` filter in the
+Template Toolkit to do this (or the ``uri`` filter to encode special
characters in URLs). If you forget, you may open up your installation
to cross-site scripting attacks.
-.. todo:: Move the below.
-
-Editing templates is a good way of doing a 'poor man's custom
-fields'.
-For example, if you don't use the :guilabel:`Status Whiteboard`, but want to
-have a free-form text entry box for :guilabel:`Build Identifier`,
-then you can just
-edit the templates to change the field labels. It's still be called
-status_whiteboard internally, but your users don't need to know that.
-.. note:: you should run :command:`./checksetup.pl` after
- editing any templates. Failure to do so may mean your changes are
- not picked up.
+You should run :command:`./checksetup.pl` after editing any templates. Failure
+to do so may mean your changes are not picked up.
.. _template-formats:
==========================
Some CGI's have the ability to use more than one template. For example,
-:file:`buglist.cgi` can output itself as RDF, or as two
-formats of HTML (complex and simple). The mechanism that provides this
-feature is extensible.
+:file:`buglist.cgi` can output itself as two formats of HTML (complex and
+simple). Each of these is a separate template. The mechanism that provides
+this feature is extensible - you can create new templates to add new formats.
-Bugzilla can support different types of output, which again can have
-multiple formats. In order to request a certain type, you can append
-the &ctype=<contenttype> (such as rdf or html) to the
-:file:`<cginame>.cgi` URL. If you would like to
-retrieve a certain format, you can use the &format=<format>
-(such as simple or complex) in the URL.
+You might use this feature to e.g. add a custom bug entry form for a
+particular subset of users or a particular type of bug.
+
+Bugzilla can also support different types of output - e.g. bugs are available
+as HTML and as XML, and this mechanism is extensible also to add new content
+types. However, instead of using such interfaces or enhancing Bugzilla to add
+more, you would be better off using the :ref:`apis` to integrate with
+Bugzilla.
To see if a CGI supports multiple output formats and types, grep the
CGI for ``get_format``. If it's not present, adding
multiple format/type support isn't too hard - see how it's done in
-other CGIs, e.g. config.cgi.
+other CGIs, e.g. :file:`config.cgi`.
To make a new format template for a CGI which supports this,
open a current template for
You now need to decide what content type you want your template
served as. The content types are defined in the
-:file:`Bugzilla/Constants.pm` file in the
-:file:`contenttypes`
+:file:`Bugzilla/Constants.pm` file in the :file:`contenttypes`
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, 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.
-
-Save the template as :file:`<stubname>-<formatname>.<contenttypetag>.tmpl`.
+Save your new template as
+:file:`<stubname>-<formatname>.<contenttypetag>.tmpl`.
Try out the template by calling the CGI as
-:file:`<cginame>.cgi?format=<formatname>&ctype=<type>` .
+``<cginame>.cgi?format=<formatname>``. Add ``&ctype=<type>`` if the type is
+not HTML.
.. _template-specific:
your Bugzilla installation.
:file:`global/variables.none.tmpl`:
- .. todo:: Need to describe the use of this file
+ This allows you to change the word 'bug' to something else (e.g. "issue")
+ throughout the interface, and also to change the name Bugzilla to something
+ else (e.g. "FooCorp Bug Tracker").
:file:`list/table.html.tmpl`:
This template controls the appearance of the bug lists created
you'll want to change this to something more appropriate for your
environment.
+.. _custom-bug-entry:
+
:file:`bug/create/create.html.tmpl` and :file:`bug/create/comment.txt.tmpl`:
You may not wish to go to the effort of creating custom fields in
Bugzilla, yet you want to make sure that each bug report contains
extensible fashion to enable you to add arbitrary HTML widgets,
such as drop-down lists or textboxes, to the bug entry page
and have their values appear formatted in the initial comment.
+
+ An example of this is the mozilla.org `guided bug submission form
+ <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_.
+ The code for this comes with the Bugzilla distribution as an example for
+ you to copy. It can be found in the files
+ :file:`create-guided.html.tmpl` and :file:`comment-guided.html.tmpl`.
+
A hidden field that indicates the format should be added inside
the form in order to make the template functional. Its value should
be the suffix of the template filename. For example, if the file
- is called :file:`create-cust.html.tmpl`, then
+ is called :file:`create-guided.html.tmpl`, then
::
- <input type="hidden" name="format" value="cust">
+ <input type="hidden" name="format" value="guided">
- should be used inside the form.
-
- An example of this is the mozilla.org
- `guided
- bug submission form <http://landfill.bugzilla.org/bugzilla-tip/enter_bug.cgi?product=WorldControl;format=guided>`_. The code for this comes with the Bugzilla
- distribution as an example for you to copy. It can be found in the
- files
- :file:`create-guided.html.tmpl` and :file:`comment-guided.html.tmpl`.
+ is used inside the form.
So to use this feature, create a custom template for
:file:`enter_bug.cgi`. The default template, on which you
BuildID: 20140303
would appear in the initial comment.
+
+ This system allows you to gather tructured data in bug reports without
+ the overhead and UI complexity of a large number of custom fields.
+++ /dev/null
-.. _cust-change-permissions:
-
-Who Can Change What
-###################
-
-Companies often have rules about which employees, or classes of employees,
-are allowed to change certain things in the bug system. For example,
-only the bug's designated QA Contact may be allowed to VERIFY the bug.
-Bugzilla has been
-designed to make it easy for you to write your own custom rules to define
-who is allowed to make what sorts of value transition.
-
-By default, assignees, QA owners and users
-with *editbugs* privileges can edit all fields of bugs,
-except group restrictions (unless they are members of the groups they
-are trying to change). Bug reporters also have the ability to edit some
-fields, but in a more restrictive manner. Other users, without
-*editbugs* privileges, cannot edit
-bugs, except to comment and add themselves to the CC list.
-
-Because this kind of change is such a common request, we have added a
-specific hook for it that :ref:`extensions` can call. It's called
-``bug_check_can_change_field``, and it's documented `in the Hooks
-documentation <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Hook.html#bug_check_can_change_field>`_.
See the `Bugzilla 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.
-
-.. todo:: 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.
+documentation on how to write an Extension. It would make sense to read
+the section on :ref:`templates`. This section explains how to achieve some
+common tasks using the Extension APIs.
Adding New Fields To Bugs
=========================
=================================
If you are adding the new fields to an object other than a bug, you need to
-go a bit lower-level.
+go a bit lower-level. With reference to the instructions above:
* In ``install_update_db``, use ``bz_add_column`` instead
The process for adding accessor functions is the same.
-Adding Configuration Panels
-===========================
+Adding Admin Configuration Panels
+=================================
+
+If you add new functionality to Bugzilla, it may well have configurable
+options or parameters. The way to allow an administrator to set those
+is to add a new configuration panel.
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
* 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:`global/setting-descs.none.tmpl`. Do this in a template hook:
:file:`hook/global/setting-descs-settings.none.tmpl`. Your code can see the
hash variable; just set more members in it.
``[% 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).
+
+.. _who-can-change-what:
+
+Altering Who Can Change What
+============================
+
+Companies often have rules about which employees, or classes of employees,
+are allowed to change certain things in the bug system. For example,
+only the bug's designated QA Contact may be allowed to VERIFY the bug.
+Bugzilla has been
+designed to make it easy for you to write your own custom rules to define
+who is allowed to make what sorts of value transition.
+
+By default, assignees, QA owners and users
+with *editbugs* privileges can edit all fields of bugs,
+except group restrictions (unless they are members of the groups they
+are trying to change). Bug reporters also have the ability to edit some
+fields, but in a more restrictive manner. Other users, without
+*editbugs* privileges, cannot edit
+bugs, except to comment and add themselves to the CC list.
+
+Because this kind of change is such a common request, we have added a
+specific hook for it that :ref:`extensions` can call. It's called
+``bug_check_can_change_field``, and it's documented `in the Hooks
+documentation <http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/Hook.html#bug_check_can_change_field>`_.
+
+Checking Syntax
+===============
+
+It's not immediately obvious how to check the syntax of your extension's
+Perl modules, if it contains any. Running :command:`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``) is what you need.
+
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`.
+In Ubuntu and Debian, it is :file:`/etc/apache2/apache2.conf`. Alternatively,
+on those latter two distributions, you can instead put the below code into a
+separate file in the directory :file:`/etc/apache2/sites-enabled/`.
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.
+(in the "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).
To configure your Apache web server to work with Bugzilla while using
mod_cgi, do the following:
-.. todo:: Shouldn't we be using sites-available/sites-enabled here?
-
#. Edit the Apache configuration file (see above).
-#. Apache uses ``<Directory>``
- directives to permit fine-grained permission setting. Add the
- following lines to a directive that applies to the location
- of your Bugzilla installation. (If such a section does not
- exist, you'll want to add one.) In this example, Bugzilla has
+#. Create a ``<Directory>`` directive that applies to the location
+ of your Bugzilla installation. In this example, Bugzilla has
been installed at :file:`/var/www/html/bugzilla`.
.. code-block:: apache
Some configuration is required to make Bugzilla work with Apache
and mod_perl.
-#. 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).
-#. Add the following information to your httpd.conf file, substituting
- where appropriate with your own local paths.
+#. Add the following information, substituting where appropriate with your
+ own local paths.
.. code-block:: apache
Please bear the following points in mind when considering using Bugzilla
under mod_perl:
-- mod_perl support in Bugzilla can take up a HUGE amount of RAM - easily
+* mod_perl support in Bugzilla can take up a HUGE amount of RAM - easily
30MB per httpd child. The more RAM you can get, the better. mod_perl is
basically trading RAM for speed. At least 2GB total system RAM is
recommended for running Bugzilla under mod_perl.
-- Under mod_perl, you have to restart Apache if you make any manual change to
+* Under mod_perl, you have to restart Apache if you make any manual change to
any Bugzilla file. You can't just reload--you have to actually
*restart* the server (as in make sure it stops and starts
again). You *can* change :file:`localconfig` and the :file:`params` file
manually, if you want, because those are re-read every time you load a page.
-- You must run in Apache's Prefork MPM (this is the default). The Worker MPM
+* You must run in Apache's Prefork MPM (this is the default). The Worker MPM
may not work -- we haven't tested Bugzilla's mod_perl support under threads.
(And, in fact, we're fairly sure it *won't* work.)
-- Bugzilla generally expects to be the only mod_perl application running on
+* Bugzilla generally expects to be the only mod_perl application running on
your entire server. It may or may not work if there are other applications also
running under mod_perl. It does try its best to play nice with other mod_perl
applications, but it still may have conflicts.
-- It is recommended that you have one Bugzilla instance running under mod_perl
+* It is recommended that you have one Bugzilla instance running under mod_perl
on your server. Bugzilla has not been tested with more than one instance running.
Bugzilla's approach to email is configured in the :guilabel:`Email` section
of the Parameters.
-.. todo:: Bug: description of mail_delivery_method talks about Qmail, and is in
- other ways wrong.
-
.. _install-MTA:
Use Another Mail Server
.. todo:: Which versions of RHEL have packages new enough for us to support them?
-.. todo:: What's the right order for all the following steps?
-
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).
+Some distributions even have a Bugzilla package, although that will vary
+in age.
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.
+is not found, just remove it from the list and reissue the command. If you
+want to use a different database or webserver, substitute the package
+names as appropriate.
Fedora and Red Hat
------------------
+The following command will install Red Hat's packaged version of Bugzilla:
+:command:`yum install bugzilla httpd mysql-server`
+
+However, if you go this route, you need to read :bug:`415605`, which details
+some problems with the Bugzilla rpm. Then, you can skip to
+:ref:`configuring your database <config-database>`. It may be useful to know
+that Fedora stores the Bugzilla files in :file:`/usr/share/bugzilla`, so
+that's where you'll run :file:`checksetup.pl`.
+
+If you want to install a version of Bugzilla from the Bugzilla project, you
+will instead need:
+
: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
libauthen-sasl-perl libtemplate-perl-doc libfile-mimeinfo-perl
libhtml-formattext-withlinks-perl libgd-dev lynx-cur`
+Gentoo
+------
+
+:command:`emerge -av bugzilla`
+
+will install Bugzilla and all its dependencies. If you don't have the vhosts
+USE flag enabled, Bugzilla will end up in :file:`/var/www/localhost/bugzilla`.
+
+Then, you can skip to :ref:`configuring your database <config-database>`.
+
Perl
====
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?
+
.. _install-perlmodules:
Perl Modules
apache
-You can run :command:`testserver.pl http://bugzilla-url/` from the command
-line to check if your web server is correctly configured.
-
-.. todo:: Does this work before doing any localconfig stuff?
-
.. _config-database:
Database Engine
need to change one or more of the other ``$db_*`` parameters.
.. note:: If you are using Oracle, ``$db_name`` should be set to
- the SID name of your database (e.g. "XE" if you are using Oracle XE).
+ the SID name of your database (e.g. ``XE`` if you are using Oracle XE).
checksetup.pl
=============
Bugzilla
========
-Your Bugzilla should now be working. Access
-:file:`http://<your-bugzilla-server>/` -
-you should see the Bugzilla front page.
-
-.. note:: The URL above may be incorrect if you installed Bugzilla into a
- subdirectory or used a symbolic link from your web site root to
- the Bugzilla directory.
-
-Next, do the :ref:`post-install-config`.
-
-.. todo:: How to we integrate the below (copied from the wiki)?
-
-Gentoo
-======
-
-Gentoo pulls in all dependencies and, if you don't have the vhosts USE flag enabled, installs Bugzilla to /var/www/localhost/bugzilla when you issue:
-
-<code># emerge -av bugzilla</code>
-
-You will then have to configure and install your database according to your needs:
-
-For a first time MySQL install:
-
-<code># mysql_install_db</code>
-
-Else:
-
-<code># mysql -u root -p<br />
-mysql>CREATE DATABASE databasename;<br />
-mysql>GRANT <privs> ON databasename.* to 'bugzillauser'@'hostname' identified by 'pa$$w0rd';</code>
-
-Fedora
-======
-
-'''Please be aware of this:''' https://bugzilla.mozilla.org/show_bug.cgi?id=415605
-(Please remove this link once determined the RPM has been repaired)
-
-Bugzilla and its dependencies are in the Fedora yum repository. To install Bugzilla and all its Perl dependencies, simply do (as root)
+Your Bugzilla should now be working. Check by running:
-<code>$ yum install bugzilla</code>
+:command:`testserver.pl http://<your-bugzilla-server>/`
-You also need to install the database engine and web server, for example MySQL and httpd:
+If that passes, access ``http://<your-bugzilla-server>/`` in your browser -
+you should see the Bugzilla front page. Of course, if you installed Bugzilla
+in a subdirectory, make sure that's in the URL.
-<code>$ yum install httpd mysql-server</code>
-
-The Fedora packages automatically do the httpd configuration, so there is no need to worry about that.
-
-To configure MySQL, you need to add the bugs user and bugs database to MySQL. You can do this with the normal MySQL tools - either use the command line, the mysqladmin tool, or the mysql-administrator GUI tool. You can also use a web-based control panel like PHPMyADMIN. Make sure the "bugs" user has write permissions ot the "bugs" database.
-
-The next step is to configure <code>/etc/bugzilla/localconfig</code> with the right database information:
-
-<pre>
-# The name of the database
-$db_name = 'bugs';
-
-# Who we connect to the database as.
-$db_user = 'bugs';
-
-# Enter your database password here. It's normally advisable to specify
-# a password for your bugzilla database user.
-# If you use apostrophe (') or a backslash (\) in your password, you'll
-# need to escape it by preceding it with a '\' character. (\') or (\)
-# (Far simpler just not to use those characters.)
-$db_pass = 'PASSWORD';
-</pre>
-
-Fedora stores the Bugzilla files in <code>/usr/share/bugzilla</code>. Change into that directory and run the <code>checksetup.pl</code> script. If any problems are encountered here, you can refer to the Bugzilla user guide.
-
-Finally, start mysqld and httpd and browse to http://localhost/bugzilla
+Next, do the :ref:`post-install-config`.
configuration file, which is usually :file:`/etc/my.cnf`
on Linux.
-By default, MySQL will only allow you to insert things
+By default on some systems, MySQL will only allow you to insert things
into the database that are smaller than 1MB.
-.. todo:: Is this still true? It's 16MB on Ubuntu 14.04...
-
Bugzilla attachments
may be larger than this. Also, Bugzilla combines all comments
on a single bug into one field for full-text searching, and the
We recommend that you allow at least 16MB packets by
adding or altering the ``max_allowed_packet`` parameter in your MySQL
-configuration in the ``[mysqld]`` section, like this:
+configuration in the ``[mysqld]`` section, so that the number is at least
+16M, like this (note that it's ``M``, not ``MB``):
::
[mysqld]
- # Allow packets up to 16MB
+ # Allow packets up to 16M
max_allowed_packet=16M
.. _mysql-small-words:
cookiebase. If your Bugzilla is at the root of your domain, you don't need
to change the default value.
-You will also need to tell Bugzilla how to :ref:`send email <email>`.
-
You may want to put your email address in the :param:`maintainer`
parameter in the :guilabel:`General` section. This will then let people
know who to contact if they see problems or hit errors.
:param:`requirelogin` parameter in the :guilabel:`User Authentication`
section, and change or clear the :param:`createemailregexp` parameter.
+You will also need to set appropriate parameters so Bugzilla knows how to
+:ref:`send email <email>`.
+
.. _config-products:
Products, Components, Versions and Milestones
=============================================
-.. todo:: WRITE ME
+Bugs in Bugzilla are categorised into Products and, inside those Products,
+Components (and, optionally, if you turn on the :param:`useclassifications`
+parameter, Classifications as a level above Products).
-.. _optional-features:
+Bugzilla comes with a single Product, called "TestProduct", which contains a
+single component, imaginatively called "TestComponent". You will want to
+create your own Products and their Components. It's OK to have just one
+Component inside a Product. Products have Versions (which represents the
+version of the software in which a bug was found) and Target Milestones
+(which represent the future version of the product in which the bug is
+hopefully to be fixed - or, for RESOLVED bugs, was fixed. You may also want
+to add some of those.
-Optional
-========
+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.
-.. todo:: HACKME
+.. _optional-features:
+
+Optional Features
+=================
Bugzilla has a number of optional features. This section describes how
to configure or enable them.
Bug Graphs
----------
-If you have installed the necessary Perl modules you
-can start collecting statistics for the nifty Bugzilla
-graphs.
-
-::
+If you have installed the necessary Perl modules, as indicated by
+:file:`checksetup.pl`, you can ask Bugzilla to regularly collect statistics
+so that you can see graphs and charts. Run:
- # crontab -e
+:command:`crontab -e`
-This should bring up the crontab file in your editor.
-Add a cron entry like this to run
-:file:`collectstats.pl`
-daily at 5 after midnight:
+This should bring up the crontab file in your editor. Add a cron entry like
+this to run :file:`collectstats.pl` daily at 5 after midnight:
.. code-block:: none
After two days have passed you'll be able to view bug graphs from
the Reports page.
-.. note:: Windows does not have 'cron', but it does have the Task
- Scheduler, which performs the same duties. There are also
- third-party tools that can be used to implement cron, such as
- `nncron <http://www.nncron.ru/>`_.
+Windows does not have 'cron', but it does have the Task Scheduler, which
+performs the same duties. There are also third-party tools that can be used
+to implement cron, such as `nncron <http://www.nncron.ru/>`_.
-.. _installation-whining-cron:
+.. _installation-whining:
-The Whining Cron
-----------------
+Whining
+-------
-What good are
-bugs if they're not annoying? To help make them more so you
-can set up Bugzilla's automatic whining system to complain at engineers
-which leave their bugs in the CONFIRMED state without triaging them.
+Users can configure Bugzilla to annoy them at regular intervals, by having
+Bugzilla execute saved searches at certain times and emailing the results to
+the user. This is known as "Whining". The details of how a user configures
+Whining is described in :ref:`whining`, but for it to work a Perl script must
+be executed at regular intervals.
-This can be done by adding the following command as a daily
-crontab entry, in the same manner as explained above for bug
-graphs. This example runs it at 12.55am.
+This can be done by adding the following repeating command, in
+the same manner as explained above for bug graphs. This example, using cron
+syntax, runs it every 15 minutes, which is the recommended interval.
.. code-block:: none
- 55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl
-
-.. note:: Windows does not have 'cron', but it does have the Task
- Scheduler, which performs the same duties. There are also
- third-party tools that can be used to implement cron, such as
- `nncron <http://www.nncron.ru/>`_.
+ */15 * * * * cd <your-bugzilla-directory> && ./whine.pl
-.. _installation-whining:
+.. _installation-whining-cron:
-Whining
--------
+Whining at Untriaged Bugs
+-------------------------
-Users can configure Bugzilla to regularly annoy
-them at regular intervals, by having Bugzilla execute saved searches
-at certain times and emailing the results to the user. This is known
-as "Whining". The process of configuring Whining is described
-in :ref:`whining`, but for it to work a Perl script must be
-executed at regular intervals.
+It's possible for bugs to languish in an untriaged state. Bugzilla has a
+specific system to issue complaints about this particular problem to all the
+relevant engineers automatically by email.
-This can be done by adding the following command as a daily
-crontab entry, in the same manner as explained above for bug
-graphs. This example runs it every 15 minutes.
+This can be done by adding the following repeating command, in
+the same manner as explained above for bug graphs. This example, using cron
+syntax, runs it at 12.55am:
.. code-block:: none
- */15 * * * * cd <your-bugzilla-directory> && ./whine.pl
-
-.. note:: Whines can be executed as often as every 15 minutes, so if you specify
- longer intervals between executions of whine.pl, some users may not
- be whined at as often as they would expect. Depending on the person,
- this can either be a very Good Thing or a very Bad Thing.
-
-.. note:: Windows does not have 'cron', but it does have the Task
- Scheduler, which performs the same duties. There are also
- third-party tools that can be used to implement cron, such as
- `nncron <http://www.nncron.ru/>`_.
+ 55 0 * * * cd <your-bugzilla-directory> && ./whineatnews.pl
.. _multiple-bz-dbs:
-Multiple Bugzilla databases with a single installation
-------------------------------------------------------
+Running Multiple Bugzillas from a Single Code Installation
+----------------------------------------------------------
-The previous instructions referred to a standard installation, with
-one unique Bugzilla database. However, you may want to host several
-distinct installations, without having several copies of the code. This is
-possible by using the PROJECT environment variable. When accessed,
+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.<PROJECT>` in the same location as
customized templates in a directory named
:file:`<PROJECT>` in the same location as the
default one (:file:`template/<langcode>`). By default
-this is :file:`template/en/default` so PROJECT's templates
+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
+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
.. code-block:: apache
- <VirtualHost 212.85.153.228:80>
- ServerName foo.bar.baz
- SetEnv PROJECT foo
- Alias /bugzilla /var/www/bugzilla
+ <VirtualHost 12.34.56.78:80>
+ ServerName bugzilla.example.com
+ SetEnv PROJECT foo
</VirtualHost>
Don't forget to also export this variable before accessing Bugzilla
-by other means, such as cron tasks for instance.
-
+by other means, such as repeating tasks like those above.
Ubuntu 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.
-0. Obtain Your Hardware
+Obtain Your Hardware
+====================
+
+Ubuntu 14.04 LTS Server requires a 64-bit processor.
+Bugzilla itself has no prerequisites beyond that, although you should pick
+reliable hardware. You can also probably use any 64-bit virtual machine
+or cloud instance that you have root access on.
+
+Install the OS
+==============
+
+Get `Ubuntu Server 14.04 LTS <http://www.ubuntu.com/download/server>`_
+and follow the `installation instructions <http://www.ubuntu.com/download/server/install-ubuntu-server>`_.
+Here are some tips:
+
+* Choose any server name you like.
+* When creating the initial Linux user, call it ``bugzilla``, give it a
+ strong password, and write that password down.
+* You do not need an encrypted home directory.
+* Choose all the defaults for the "partitioning" part (excepting of course
+ where the default is "No" and you need to press "Yes" to continue).
+* Choose "install security updates automatically" unless you want to do
+ them manually.
+* From the install options, choose "OpenSSH Server" and "LAMP Server".
+* Set the password for the MySQL root user to a strong password, and write
+ that password down.
+* Install the Grub boot loader to the Master Boot Record.
+
+Reboot when the installer finishes.
+
+Become root
+===========
+
+ssh to the machine as the 'bugzilla' user, or start a console. Then:
+
+:command:`sudo su`
+
+Install Prerequisites
+=====================
- Ubuntu 14.04 LTS Server requires a 64-bit processor.
- Bugzilla itself has no prerequisites beyond that, although you should pick
- reliable hardware. You can also probably use any 64-bit virtual machine
- or cloud instance that you have root access on.
+:command:`apt-get install git nano`
-1. Install the OS
+: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`
- Get `Ubuntu Server 14.04 LTS <http://www.ubuntu.com/download/server>`_
- and follow the `installation instructions <http://www.ubuntu.com/download/server/install-ubuntu-server>`_.
- Here are some tips:
+This will take a little while. It's split into two commands so you can do
+the next steps (up to step 7) in another terminal while you wait for the
+second command to finish. If you start another terminal, you will need to
+:command:`sudo su` again.
- * Choose any server name you like.
- * When creating the initial Linux user, call it ``bugzilla``, give it a
- strong password, and write that password down.
- * You do not need an encrypted home directory.
- * Choose all the defaults for the "partitioning" part (excepting of course
- where the default is "No" and you need to press "Yes" to continue).
- * Choose "install security updates automatically" unless you want to do
- them manually.
- * From the install options, choose "OpenSSH Server" and "LAMP Server".
- * Set the password for the MySQL root user to a strong password, and write
- that password down.
- * Install the Grub boot loader to the Master Boot Record.
+Download Bugzilla
+=================
- Reboot when the installer finishes.
+Get it from our Git repository:
-2. Become root
+:command:`cd /var/www`
- ssh to the machine as the 'bugzilla' user, or start a console. Then:
-
- :command:`sudo su`
-
-3. Install Prerequisites
+:command:`rm -rf html`
- :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`
+:command:`git clone https://git.mozilla.org/bugzilla/bugzilla html`
- This will take a little while. It's split into two commands so you can do
- the next steps (up to step 7) in another terminal while you wait for the
- second command to finish. If you start another terminal, you will need to
- :command:`sudo su` again.
+:command:`cd html`
-4. Download Bugzilla
+:command:`git checkout bugzilla-stable`
- Get it from our Git repository:
+You will get a notification about having a detached HEAD. Don't worry,
+your head is still firmly on your shoulders.
- :command:`cd /var/www`
+.. todo:: is this the right way to get the current bugzilla-stable code? Or
+ should we pull directly from a branch?
+
+Configure MySQL
+===============
- :command:`rm -rf html`
+The following instructions use the simple :file:`nano` editor, but feel
+free to use any text editor you are comfortable with.
- :command:`git clone https://git.mozilla.org/bugzilla/bugzilla html`
+:command:`nano /etc/mysql/my.cnf`
- :command:`cd html`
+Set the following values, which increase the maximum attachment size and
+make it possible to search for short words and terms:
- :command:`git checkout bugzilla-stable`
+* Alter on Line 52: ``max_allowed_packet=100M``
+* Add as new line 31, in the ``[mysqld]`` section: ``ft_min_word_len=2``
- You will get a notification about having a detached HEAD. Don't worry,
- your head is still firmly on your shoulders.
+Save and exit.
- .. todo:: is this the right way to get the current bugzilla-stable code? Or
- should we pull directly from a branch?
-
-5. Configure MySQL
+Restart MySQL:
- The following instructions use the simple :file:`nano` editor, but feel
- free to use any text editor you are comfortable with.
+:command:`service mysql restart`
- :command:`nano /etc/mysql/my.cnf`
+Configure Apache
+================
- Set the following values, which increase the maximum attachment size and
- make it possible to search for short words and terms:
+:command:`nano /etc/apache2/sites-available/bugzilla.conf`
- * Alter on Line 52: ``max_allowed_packet=100M``
- * Add as new line 31, in the ``[mysqld]`` section: ``ft_min_word_len=2``
+Paste in the following and save:
- Save and exit.
+.. code-block:: none
- .. todo:: default value of maxattachmentsize is 1MB. Default value of max_allowed_packet
- is 16MB. Should we just omit this step entirely, for simplicity? Do we need
- ft_min_word_len changed?
+ ServerName localhost
- .. todo:: docs for maxattachmentsize should mention max_allowed_packet. File bug.
+ <Directory /var/www/html>
+ AddHandler cgi-script .cgi
+ Options +ExecCGI
+ DirectoryIndex index.cgi index.html
+ AllowOverride Limit FileInfo Indexes Options
+ </Directory>
- Restart MySQL:
-
- :command:`service mysql restart`
-
-6. Configure Apache
+:command:`a2ensite bugzilla`
- :command:`nano /etc/apache2/sites-available/bugzilla.conf`
+:command:`a2enmod cgi headers expires`
- Paste in the following and save:
+:command:`service apache2 restart`
- .. code-block:: none
+Check Setup
+===========
- ServerName localhost
+Bugzilla comes with a :file:`checksetup.pl` script which helps with the
+installation process. It will need to be run twice. The first time, it
+generates a config file (called :file:`localconfig`) for the database
+access information, and the second time (step 10)
+it uses the info you put in the config file to set up the database.
- <Directory /var/www/html>
- AddHandler cgi-script .cgi
- Options +ExecCGI
- DirectoryIndex index.cgi index.html
- AllowOverride Limit FileInfo Indexes Options
- </Directory>
+:command:`cd /var/www/html`
- :command:`a2ensite bugzilla`
+:command:`./checksetup.pl`
- :command:`a2enmod cgi headers expires`
+Edit :file:`localconfig`
+========================
- :command:`service apache2 restart`
+:command:`nano localconfig`
-8. Check Setup
+You will need to set the following values:
- Bugzilla comes with a :file:`checksetup.pl` script which helps with the
- installation process. It will need to be run twice. The first time, it
- generates a config file (called :file:`localconfig`) for the database
- access information, and the second time (step 10)
- it uses the info you put in the config file to set up the database.
+* Line 29: set ``$webservergroup`` to ``www-data``
+* Line 60: set ``$db_user`` to ``root``
+* Line 67: set ``$db_pass`` to the MySQL root user password you created
+ when installing Ubuntu
- :command:`cd /var/www/html`
-
- :command:`./checksetup.pl`
-
-9. Edit :file:`localconfig`
+.. todo:: Given this is a quick setup on a dedicated box, is it OK to use the
+ MySQL root user?
+
+Check Setup (again)
+===================
- :command:`nano localconfig`
+Run the :file:`checksetup.pl` script again to set up the database.
- You will need to set the following values:
-
- * Line 29: set ``$webservergroup`` to ``www-data``
- * Line 60: set ``$db_user`` to ``root``
- * Line 67: set ``$db_pass`` to the MySQL root user password you created
- when installing Ubuntu
+:command:`./checksetup.pl`
- .. todo:: Given this is a quick setup on a dedicated box, is it OK to use the
- MySQL root user?
-
-10. Check Setup (again)
+It will ask you to give an email address, real name and password for the
+first Bugzilla account to be created, which will be an administrator.
+Write down the email address and password you set.
- Run the :file:`checksetup.pl` script again to set up the database.
-
- :command:`./checksetup.pl`
+Test Server
+===========
- It will ask you to give an email address, real name and password for the
- first Bugzilla account to be created, which will be an administrator.
- Write down the email address and password you set.
+:command:`./testserver.pl http://localhost/`
-11. Test Server
+All the tests should pass. (Note: currently, the first one will give a
+warning instead. You can ignore that. :bug:`1040728`.)
- :command:`./testserver.pl http://localhost/`
+.. todo:: Also, Chart::Base gives deprecation warnings :-|
+ https://rt.cpan.org/Public/Bug/Display.html?id=79658 , unfixed for
+ 2 years. :bug:`1070117`.
- All the tests should pass. (Note: currently, the first one will give a
- warning instead. You can ignore that. Bug 1040728.)
+Access Via Web Browser
+======================
- .. todo:: Also, Chart::Base gives deprecation warnings :-|
-
-12. Access Via Web Browser
+Access the front page:
- Access the front page:
+:command:`lynx http://localhost/`
- :command:`lynx http://localhost/`
+It's not really possible to use Bugzilla for real through Lynx, but you
+can view the front page to validate visually that it's up and running.
- It's not really possible to use Bugzilla for real through Lynx, but you
- can view the front page to validate visually that it's up and running.
-
- You might well need to configure your DNS such that the server has, and
- is reachable by, a name rather than IP address. Doing so is out of scope
- of this document. In the mean time, it is available on your local network
- at ``http://<ip address>/``, where ``<ip address>`` is (unless you have
- a complext network setup) the "inet addr" value displayed when you run
- :command:`ifconfig eth0`.
+You might well need to configure your DNS such that the server has, and
+is reachable by, a name rather than IP address. Doing so is out of scope
+of this document. In the mean time, it is available on your local network
+at ``http://<ip address>/``, where ``<ip address>`` is (unless you have
+a complex network setup) the "inet addr" value displayed when you run
+:command:`ifconfig eth0`.
-13. Configure Bugzilla
+Configure Bugzilla
+==================
- Once you have worked out how to access your Bugzilla in a graphical
- web browser, bring up the front page, click :guilabel:`Log In` in the
- header, and log in as the admin user you defined in step 10.
+Once you have worked out how to access your Bugzilla in a graphical
+web browser, bring up the front page, click :guilabel:`Log In` in the
+header, and log in as the admin user you defined in step 10.
- Click the :guilabel:`Parameters` link on the page it gives you, and set
- the following parameters in the :guilabel:`Required Settings` section:
+Click the :guilabel:`Parameters` link on the page it gives you, and set
+the following parameters in the :guilabel:`Required Settings` section:
- * :param:`urlbase`:
- :paramval:`http://<servername>/` or :paramval:`http://<ip address>/`
+* :param:`urlbase`:
+ :paramval:`http://<servername>/` or :paramval:`http://<ip address>/`
- Click :guilabel:`Save Changes` at the bottom of the page.
+Click :guilabel:`Save Changes` at the bottom of the page.
- There are several ways to get Bugzilla to send email. The easiest is to
- use Gmail, so we do that here so you have it working. Visit
- https://gmail.com and create a new Gmail account for your Bugzilla to use.
- Then, open the :guilabel:`Email` section of the Parameters using the link
- in the left column, and set the following parameter values:
-
- * :param:`mail_delivery_method`: :paramval:`SMTP`
- * :param:`mailfrom`: :paramval:`new_gmail_address@gmail.com`
- * :param:`smtpserver`: :paramval:`smtp.gmail.com:465`
- * :param:`smtp_username`: :paramval:`new_gmail_address@gmail.com`
- * :param:`smtp_password`: :paramval:`new_gmail_password`
- * :param:`smtp_ssl`: :paramval:`On`
+There are several ways to get Bugzilla to send email. The easiest is to
+use Gmail, so we do that here so you have it working. Visit
+https://gmail.com and create a new Gmail account for your Bugzilla to use.
+Then, open the :guilabel:`Email` section of the Parameters using the link
+in the left column, and set the following parameter values:
- Click :guilabel:`Save Changes` at the bottom of the page.
+* :param:`mail_delivery_method`: :paramval:`SMTP`
+* :param:`mailfrom`: :paramval:`new_gmail_address@gmail.com`
+* :param:`smtpserver`: :paramval:`smtp.gmail.com:465`
+* :param:`smtp_username`: :paramval:`new_gmail_address@gmail.com`
+* :param:`smtp_password`: :paramval:`new_gmail_password`
+* :param:`smtp_ssl`: :paramval:`On`
- .. todo:: There should be a "send test email" button on that page
+Click :guilabel:`Save Changes` at the bottom of the page.
- And you're all ready to go. :-)
+And you're all ready to go. :-)
small and development Bugzilla installations.
Once you have SQLite installed, no additional configuration is required to
-run Bugzilla. Simply set ``$db_driver`` to ``Sqlite`` (case-sensitive) in
-:file:`localconfig`, when you get to that point in the installation.
+run Bugzilla.
.. todo:: This doesn't work - gives a timezone-related error on my box.
-The database will be stored in :file:`data/db/$db_name`, where ``$db_name``
-is the database name defined in :file:`localconfig`.
+The database will be stored in :file:`$BUGZILLA_HOME/data/db/$db_name`, where
+``$db_name`` is the database name defined in :file:`localconfig`.
<http://www.bugzilla.org/docs/tip/en/html/api/Bugzilla/WebService/Server/REST.html>`_
which is the currently-recommended API for integrating with Bugzilla. The
current REST API is version 1. It is stable, and so will not be changed in a
-backwardly-incompatible way.
+backwardly-incompatible way. **This is the currently-recommended API for
+new development.**
-BzAPI-Compatible REST
-=====================
+BzAPI/BzAPI-Compatible REST
+===========================
The first ever REST API for Bugzilla was implemented using an external proxy
called `BzAPI <https://wiki.mozilla.org/Bugzilla:BzAPI>`_. This became popular
* Any string from the UI:
:guilabel:`Administration`
+
+* A specific BMO bug:
+ :bug:`201069`
*Additional Comments:*
You can add your two cents to the bug discussion here, if you have
something worthwhile to say.
+
+.. _flags:
+
+Flags
+=====
+
+Flags are a way to attach a specific status to a bug or attachment,
+either ``+`` or ``-``. The meaning of these symbols depends on the name of
+the flag itself, but contextually they could mean pass/fail,
+accept/reject, approved/denied, or even a simple yes/no. If your site
+allows requestable flags, then users may set a flag to ``?`` as a
+request to another user that they look at the bug/attachment, and set
+the flag to its correct status.
+
+.. _flags-simpleexample:
+
+A Simple Example
+----------------
+
+A developer might want to ask their manager,
+"Should we fix this bug before we release version 2.0?"
+They might want to do this for a *lot* of bugs,
+so they decide to streamline the process. So:
+
+#. The Bugzilla administrator creates a flag type called
+ ``blocking2.0`` that shows up on all bugs in
+ your product.
+ It shows up on the :guilabel:`Show Bug` screen
+ as the text ``blocking2.0`` with a drop-down box next
+ to it. The drop-down box contains four values: an empty space,
+ ``?``, ``-``, and ``+``.
+
+#. The developer sets the flag to ``?``.
+
+#. The manager sees the ``blocking2.0``
+ flag with a ``?`` value.
+
+#. If the manager thinks the feature should go into the product
+ before version 2.0 can be released, he sets the flag to
+ ``+``. Otherwise, he sets it to ``-``.
+
+#. Now, every Bugzilla user who looks at the bug knows whether or
+ not the bug needs to be fixed before release of version 2.0.
+
+.. _flags-about:
+
+About Flags
+-----------
+
+Flags can have four values:
+
+``?``
+ A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
+
+``-``
+ The status has been set negatively. (The question has been answered ``no``.)
+
+``+``
+ The status has been set positively.
+ (The question has been answered ``yes``.)
+
+``_``
+ ``unset`` actually shows up as a blank space. This just means that nobody
+ has expressed an opinion (or asked someone else to express an opinion)
+ about the matter covered by this flag.
+
+.. _flag-askto:
+
+Flag Requests
+-------------
+
+If a flag has been defined as 'requestable', and a user has enough privileges
+to request it (see below), the user can set the flag's status to ``?``.
+This status indicates that someone (a.k.a. "the requester") is asking
+someone else to set the flag to either ``+`` or ``-``.
+
+If a flag has been defined as 'specifically requestable',
+a text box will appear next to the flag into which the requester may
+enter a Bugzilla username. That named person (a.k.a. "the requestee")
+will receive an email notifying them of the request, and pointing them
+to the bug/attachment in question.
+
+If a flag has *not* been defined as 'specifically requestable',
+then no such text-box will appear. A request to set this flag cannot be made
+of any specific individual, but must be asked "to the wind".
+A requester may "ask the wind" on any flag simply by leaving the text-box
+blank.
+
+.. _flag-types:
+
+.. _flag-type-attachment:
+
+Attachment Flags
+----------------
+
+There are two types of flags: bug flags and attachment flags.
+
+Attachment flags are used to ask a question about a specific
+attachment on a bug.
+
+Many Bugzilla installations use this to
+request that one developer ``review`` another
+developer's code before they check it in. They attach the code to
+a bug report, and then set a flag on that attachment called
+``review`` to
+``review? reviewer@example.com``.
+reviewer\@example.com is then notified by email that
+he has to check out that attachment and approve it or deny it.
+
+For a Bugzilla user, attachment flags show up in three places:
+
+#. On the list of attachments in the :guilabel:`Show Bug`
+ screen, you can see the current state of any flags that
+ have been set to ``?``, ``+``, or ``-``. You can see who asked about
+ the flag (the requester), and who is being asked (the
+ requestee).
+
+#. When you edit an attachment, you can
+ see any settable flag, along with any flags that have
+ already been set. The :guilabel:`Edit Attachment`
+ screen is where you set flags to ``?``, ``-``, ``+``, or unset them.
+
+#. Requests are listed in the :guilabel:`Request Queue`, which
+ is accessible from the :guilabel:`My Requests` link (if you are
+ logged in) or :guilabel:`Requests` link (if you are logged out)
+ visible on all pages.
+
+.. _flag-type-bug:
+
+Bug Flags
+---------
+
+Bug flags are used to set a status on the bug itself. You can
+see Bug Flags in the :guilabel:`Show Bug` and :guilabel:`Requests`
+screens, as described above.
+
+Only users with enough privileges (see below) may set flags on bugs.
+This doesn't necessarily include the assignee, reporter, or users with the
+:group:`editbugs` permission.
projects / thirdparty / bugzilla.git / commitdiff
