From 5af060abe8347ccac35038d40577fd09c07f64c9 Mon Sep 17 00:00:00 2001 From: David Lawrence Date: Fri, 17 Jul 2015 13:34:05 +0000 Subject: Bug 1177497: Backport upstreams 5.0 rST docs to BMO and make publicly available at https://bmo.readthedocs.org --- docs/en/rst/administering/categorization.rst | 416 ++++++++++++++ docs/en/rst/administering/custom-fields.rst | 149 +++++ docs/en/rst/administering/extensions.rst | 18 + docs/en/rst/administering/field-values.rst | 45 ++ docs/en/rst/administering/flags.rst | 155 ++++++ docs/en/rst/administering/groups.rst | 191 +++++++ docs/en/rst/administering/index.rst | 26 + docs/en/rst/administering/keywords.rst | 16 + docs/en/rst/administering/parameters.rst | 794 +++++++++++++++++++++++++++ docs/en/rst/administering/preferences.rst | 10 + docs/en/rst/administering/quips.rst | 38 ++ docs/en/rst/administering/users.rst | 244 ++++++++ docs/en/rst/administering/whining.rst | 145 +++++ docs/en/rst/administering/workflow.rst | 34 ++ 14 files changed, 2281 insertions(+) create mode 100644 docs/en/rst/administering/categorization.rst create mode 100644 docs/en/rst/administering/custom-fields.rst create mode 100644 docs/en/rst/administering/extensions.rst create mode 100644 docs/en/rst/administering/field-values.rst create mode 100644 docs/en/rst/administering/flags.rst create mode 100644 docs/en/rst/administering/groups.rst create mode 100644 docs/en/rst/administering/index.rst create mode 100644 docs/en/rst/administering/keywords.rst create mode 100644 docs/en/rst/administering/parameters.rst create mode 100644 docs/en/rst/administering/preferences.rst create mode 100644 docs/en/rst/administering/quips.rst create mode 100644 docs/en/rst/administering/users.rst create mode 100644 docs/en/rst/administering/whining.rst create mode 100644 docs/en/rst/administering/workflow.rst (limited to 'docs/en/rst/administering') diff --git a/docs/en/rst/administering/categorization.rst b/docs/en/rst/administering/categorization.rst new file mode 100644 index 000000000..383b9341d --- /dev/null +++ b/docs/en/rst/administering/categorization.rst @@ -0,0 +1,416 @@ +.. _categorization: + +=============================================================== +Classifications, Products, Components, Versions, and Milestones +=============================================================== + +Bugs in Bugzilla are classified into one of a set of admin-defined Components. +Components are themselves each part of a single Product. Optionally, Products +can be part of a single Classification, adding a third level to the hierarchy. + +.. _classifications: + +Classifications +############### + +Classifications are used to group several related products into one +distinct entity. + +For example, if a company makes computer games, +they could have a classification of "Games", and a separate +product for each game. This company might also have a +``Common`` classification, containing products representing units of +technology used in multiple games, and perhaps an ``Other`` classification +containing a few special products that represent items that are not actually +shipping products (for example, "Website", or "Administration"). + +The classifications layer is disabled by default; it can be turned +on or off using the :param:`useclassification` parameter +in the *Bug Fields* section of :ref:`parameters`. + +Access to the administration of classifications is controlled using +the *editclassifications* system group, which defines +a privilege for creating, destroying, and editing classifications. + +When activated, classifications will introduce an additional +step when filling bugs (dedicated to classification selection), and they +will also appear in the advanced search form. + +.. _products: + +Products +######## + +Products usually represent real-world shipping products. +Many of Bugzilla's settings are configurable on a per-product basis. + +When creating or editing products the following options are +available: + +Product + The name of the product + +Description + A brief description of the product + +Open for bug entry + Deselect this box to prevent new bugs from being + entered against this product. + +Enable the UNCONFIRMED status in this product + Select this option if you want to use the UNCONFIRMED status + (see :ref:`workflow`) + +Default milestone + Select the default milestone for this product. + +Version + Specify the default version for this product. + +Create chart datasets for this product + Select to make chart datasets available for this product. + +It is compulsory to create at least one :ref:`component ` in a product, and +so you will be asked for the details of that too. + +When editing a product you can change all of the above, and there is also a +link to edit Group Access Controls; see :ref:`product-group-controls`. + +.. _create-product: + +Creating New Products +===================== + +To create a new product: + +#. Select ``Administration`` from the footer and then + choose ``Products`` from the main administration page. + +#. Select the ``Add`` link in the bottom right. + +#. Enter the details as outlined above. + +.. _edit-products: + +Editing Products +================ + +To edit an existing product, click the "Products" link from the +"Administration" page. If the :param:`useclassification` parameter is +turned on, a table of existing classifications is displayed, +including an "Unclassified" category. The table indicates how many products +are in each classification. Click on the classification name to see its +products. If the :param:`useclassification` parameter is not in use, the table +lists all products directly. The product table summarizes the information +defined when the product was created. Click on the product name to edit these +properties, and to access links to other product attributes such as the +product's components, versions, milestones, and group access controls. + +.. _comps-vers-miles-products: + +Adding or Editing Components, Versions and Target Milestones +============================================================ + +To add new or edit existing Components, Versions, or Target Milestones +to a Product, select the "Edit Components", "Edit Versions", or "Edit +Milestones" links from the "Edit Product" page. A table of existing +Components, Versions, or Milestones is displayed. Click on an item name +to edit the properties of that item. Below the table is a link to add +a new Component, Version, or Milestone. + +For more information on components, see :ref:`components`. + +For more information on versions, see :ref:`versions`. + +For more information on milestones, see :ref:`milestones`. + +.. _product-group-controls: + +Assigning Group Controls to Products +==================================== + +On the ``Edit Product`` page, there is a link called +``Edit Group Access Controls``. The settings on this page +control the relationship of the groups to the product being edited. + +Group Access Controls are an important aspect of using groups for +isolating products and restricting access to bugs filed against those +products. For more information on groups, including how to create, edit, +add users to, and alter permission of, see :ref:`groups`. + +After selecting the "Edit Group Access Controls" link from the "Edit +Product" page, a table containing all user-defined groups for this +Bugzilla installation is displayed. The system groups that are created +when Bugzilla is installed are not applicable to Group Access Controls. +Below is description of what each of these fields means. + +Groups may be applicable (i.e. bugs in this product can be associated +with this group), default (i.e. bugs in this product are in this group +by default), and mandatory (i.e. bugs in this product must be associated +with this group) for each product. Groups can also control access +to bugs for a given product, or be used to make bugs for a product +totally read-only unless the group restrictions are met. The best way to +understand these relationships is by example. See +:ref:`group-control-examples` for examples of +product and group relationships. + +.. note:: Products and Groups are not limited to a one-to-one relationship. + Multiple groups can be associated with the same product, and groups + can be associated with more than one product. + +If any group has *Entry* selected, then the +product will restrict bug entry to only those users +who are members of *all* the groups with +*Entry* selected. + +If any group has *Canedit* selected, +then the product will be read-only for any users +who are not members of *all* of the groups with +*Canedit* selected. *Only* users who +are members of all the *Canedit* groups +will be able to edit bugs for this product. This is an additional +restriction that enables finer-grained control over products rather +than just all-or-nothing access levels. + +The following settings let you +choose privileges on a *per-product basis*. +This is a convenient way to give privileges to +some users for some products only, without having +to give them global privileges which would affect +all products. + +Any group having *editcomponents* +selected allows users who are in this group to edit all +aspects of this product, including components, milestones, +and versions. + +Any group having *canconfirm* selected +allows users who are in this group to confirm bugs +in this product. + +Any group having *editbugs* selected allows +users who are in this group to edit all fields of +bugs in this product. + +The *MemberControl* and +*OtherControl* are used in tandem to determine which +bugs will be placed in this group. The only allowable combinations of +these two parameters are listed in a table on the "Edit Group Access Controls" +page. Consult this table for details on how these fields can be used. +Examples of different uses are described below. + +.. _group-control-examples: + +Common Applications of Group Controls +===================================== + +The use of groups is best explained by providing examples that illustrate +configurations for common use cases. The examples follow a common syntax: +*Group: Entry, MemberControl, OtherControl, CanEdit, +EditComponents, CanConfirm, EditBugs*, where "Group" is the name +of the group being edited for this product. The other fields all +correspond to the table on the "Edit Group Access Controls" page. If any +of these options are not listed, it means they are not checked. + +Basic Product/Group Restriction +------------------------------- + +Suppose there is a product called "Bar". You would like to make it so that only +users in the group "Foo" can enter bugs in the "Bar" product. Additionally, +bugs filed in product "Bar" must be visible only to users in "Foo" (plus, by +default, the reporter, assignee, and CC list of each bug) at all times. +Furthermore, only members of group "Foo" should be able to edit bugs filed +against product "Bar", even if other users could see the bug. This arrangement +would achieved by the following: + +:: + + Product Bar: + foo: ENTRY, MANDATORY/MANDATORY, CANEDIT + +Perhaps such strict restrictions are not needed for product "Bar". Instead, +you would like to make it so that only members of group "Foo" can +enter bugs in product "Bar", but bugs in "Bar" are not required to be +restricted in visibility to people in "Foo". Anyone with permission +to edit a particular bug in product "Bar" can put the bug in group "Foo", even +if they themselves are not in "Foo". + +Furthermore, anyone in group "Foo" can edit all aspects of the components of +product "Bar", can confirm bugs in product "Bar", and can edit all fields of +any bug in product "Bar". That would be done like this: + +:: + + Product Bar: + foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS + +General User Access With Security Group +--------------------------------------- + +To permit any user to file bugs against "Product A", +and to permit any user to submit those bugs into a +group called "Security": + +:: + + Product A: + security: SHOWN/SHOWN + +General User Access With A Security Product +------------------------------------------- + +To permit any user to file bugs against product called "Security" +while keeping those bugs from becoming visible to anyone +outside the group "SecurityWorkers" (unless a member of the +"SecurityWorkers" group removes that restriction): + +:: + + Product Security: + securityworkers: DEFAULT/MANDATORY + +Product Isolation With a Common Group +------------------------------------- + +To permit users of "Product A" to access the bugs for +"Product A", users of "Product B" to access the bugs for +"Product B", and support staff, who are members of the "Support +Group" to access both, three groups are needed: + +#. Support Group: Contains members of the support staff. + +#. AccessA Group: Contains users of product A and the Support group. + +#. AccessB Group: Contains users of product B and the Support group. + +Once these three groups are defined, the product group controls +can be set to: + +:: + + Product A: + AccessA: ENTRY, MANDATORY/MANDATORY + Product B: + AccessB: ENTRY, MANDATORY/MANDATORY + +Perhaps the "Support Group" wants more control. For example, +the "Support Group" could be permitted to make bugs inaccessible to +users of both groups "AccessA" and "AccessB". +Then, the "Support Group" could be permitted to publish +bugs relevant to all users in a third product (let's call it +"Product Common") that is read-only +to anyone outside the "Support Group". In this way the "Support Group" +could control bugs that should be seen by both groups. +That configuration would be: + +:: + + Product A: + AccessA: ENTRY, MANDATORY/MANDATORY + Support: SHOWN/NA + Product B: + AccessB: ENTRY, MANDATORY/MANDATORY + Support: SHOWN/NA + Product Common: + Support: ENTRY, DEFAULT/MANDATORY, CANEDIT + +Make a Product Read Only +------------------------ + +Sometimes a product is retired and should no longer have +new bugs filed against it (for example, an older version of a software +product that is no longer supported). A product can be made read-only +by creating a group called "readonly" and adding products to the +group as needed: + +:: + + Product A: + ReadOnly: ENTRY, NA/NA, CANEDIT + +.. note:: For more information on Groups outside of how they relate to products + see :ref:`groups`. + +.. _components: + +Components +########## + +Components are subsections of a Product. E.g. the computer game +you are designing may have a "UI" +component, an "API" component, a "Sound System" component, and a +"Plugins" component, each overseen by a different programmer. It +often makes sense to divide Components in Bugzilla according to the +natural divisions of responsibility within your Product or +company. + +Each component has a default assignee and, if you turned it on in the :ref:`parameters`, +a QA Contact. The default assignee should be the primary person who fixes bugs in +that component. The QA Contact should be the person who will ensure +these bugs are completely fixed. The Assignee, QA Contact, and Reporter +will get email when new bugs are created in this Component and when +these bugs change. Default Assignee and Default QA Contact fields only +dictate the *default assignments*; +these can be changed on bug submission, or at any later point in +a bug's life. + +To create a new Component: + +#. Select the ``Edit components`` link + from the ``Edit product`` page. + +#. Select the ``Add`` link in the bottom right. + +#. Fill out the ``Component`` field, a + short ``Description``, the + ``Default Assignee``, ``Default CC List``, + and ``Default QA Contact`` (if enabled). + The ``Component Description`` field may contain a + limited subset of HTML tags. The ``Default Assignee`` + field must be a login name already existing in the Bugzilla database. + +.. _versions: + +Versions +######## + +Versions are the revisions of the product, such as "Flinders +3.1", "Flinders 95", and "Flinders 2000". Version is not a multi-select +field; the usual practice is to select the earliest version known to have +the bug. + +To create and edit Versions: + +#. From the "Edit product" screen, select "Edit Versions". + +#. You will notice that the product already has the default + version "undefined". Click the "Add" link in the bottom right. + +#. Enter the name of the Version. This field takes text only. + Then click the "Add" button. + +.. _milestones: + +Milestones +########## + +Milestones are "targets" that you plan to get a bug fixed by. For +example, if you have a bug that you plan to fix for your 3.0 release, it +would be assigned the milestone of 3.0. + +.. note:: Milestone options will only appear for a Product if you turned + on the :param:`usetargetmilestone` parameter in the "Bug Fields" tab of + the :ref:`parameters` page. + +To create new Milestones and set Default Milestones: + +#. Select "Edit milestones" from the "Edit product" page. + +#. Select "Add" in the bottom right corner. + +#. Enter the name of the Milestone in the "Milestone" field. You + can optionally set the "sortkey", which is a positive or negative + number (-32768 to 32767) that defines where in the list this particular + milestone appears. This is because milestones often do not + occur in alphanumeric order; for example, "Future" might be + after "Release 1.2". Select "Add". diff --git a/docs/en/rst/administering/custom-fields.rst b/docs/en/rst/administering/custom-fields.rst new file mode 100644 index 000000000..29cc72e62 --- /dev/null +++ b/docs/en/rst/administering/custom-fields.rst @@ -0,0 +1,149 @@ +.. _custom-fields: + +Custom Fields +############# + +Custom Fields are fields defined by the administrator, in addition to those +which come with Bugzilla by default. Custom Fields are treated like any other +field—they can be set in bugs and used for search queries. + +Administrators should keep in mind that +adding too many fields can make the user interface more complicated and +harder to use. Custom Fields should be added only when necessary and with +careful consideration. + +.. note:: Before adding a Custom Field, make sure that Bugzilla cannot already + do the desired behavior. Many Bugzilla options are not enabled by + default, and many times Administrators find that simply enabling + certain options that already exist is sufficient. + +Administrators can manage Custom Fields using the +``Custom Fields`` link on the Administration page. The Custom +Fields administration page displays a list of Custom Fields, if any exist, +and a link to "Add a new custom field". + +.. _add-custom-fields: + +Adding Custom Fields +==================== + +To add a new Custom Field, click the "Add a new custom field" link. This +page displays several options for the new field, described below. + +The following attributes must be set for each new custom field: + +- *Name:* + The name of the field in the database, used internally. This name + MUST begin with ``cf_`` to prevent confusion with + standard fields. If this string is omitted, it will + be automatically added to the name entered. + +- *Description:* + A brief string used as the label for this Custom Field. + That is the string that users will see, and it should be + short and explicit. + +- *Type:* + The type of field to create. There are + several types available: + + Bug ID: + A field where you can enter the ID of another bug from + the same Bugzilla installation. To point to a bug in a remote + installation, use the See Also field instead. + Large Text Box: + A multiple line box for entering free text. + Free Text: + A single line box for entering free text. + Multiple-Selection Box: + A list box where multiple options + can be selected. After creating this field, it must be edited + to add the selection options. See + :ref:`edit-values-list` for information about + editing legal values. + Drop Down: + A list box where only one option can be selected. + After creating this field, it must be edited to add the + selection options. See + :ref:`edit-values-list` for information about + editing legal values. + Date/Time: + A date field. This field appears with a + calendar widget for choosing the date. + +- *Sortkey:* + Integer that determines in which order Custom Fields are + displayed in the User Interface, especially when viewing a bug. + Fields with lower values are displayed first. + +- *Reverse Relationship Description:* + When the custom field is of type ``Bug ID``, you can + enter text here which will be used as label in the referenced + bug to list bugs which point to it. This gives you the ability + to have a mutual relationship between two bugs. + +- *Can be set on bug creation:* + Boolean that determines whether this field can be set on + bug creation. If not selected, then a bug must be created + before this field can be set. See :ref:`filing` + for information about filing bugs. + +- *Displayed in bugmail for new bugs:* + Boolean that determines whether the value set on this field + should appear in bugmail when the bug is filed. This attribute + has no effect if the field cannot be set on bug creation. + +- *Is obsolete:* + Boolean that determines whether this field should + be displayed at all. Obsolete Custom Fields are hidden. + +- *Is mandatory:* + Boolean that determines whether this field must be set. + For single and multi-select fields, this means that a (non-default) + value must be selected; for text and date fields, some text + must be entered. + +- *Field only appears when:* + A custom field can be made visible when some criteria is met. + For instance, when the bug belongs to one or more products, + or when the bug is of some given severity. If left empty, then + the custom field will always be visible, in all bugs. + +- *Field that controls the values that appear in this field:* + When the custom field is of type ``Drop Down`` or + ``Multiple-Selection Box``, you can restrict the + availability of the values of the custom field based on the + value of another field. This criteria is independent of the + criteria used in the ``Field only appears when`` + setting. For instance, you may decide that some given value + ``valueY`` is only available when the bug status + is RESOLVED while the value ``valueX`` should + always be listed. + Once you have selected the field that should control the + availability of the values of this custom field, you can + edit values of this custom field to set the criteria; see + :ref:`edit-values-list`. + +.. _edit-custom-fields: + +Editing Custom Fields +===================== + +As soon as a Custom Field is created, its name and type cannot be +changed. If this field is a drop-down menu, its legal values can +be set as described in :ref:`edit-values-list`. All +other attributes can be edited as described above. + +.. _delete-custom-fields: + +Deleting Custom Fields +====================== + +Only custom fields that are marked as obsolete, and that have never +been used, can be deleted completely (else the integrity +of the bug history would be compromised). For custom fields marked +as obsolete, a "Delete" link will appear in the ``Action`` +column. If the custom field has been used in the past, the deletion +will be rejected. Marking the field as obsolete, however, is sufficient +to hide it from the user interface entirely. + diff --git a/docs/en/rst/administering/extensions.rst b/docs/en/rst/administering/extensions.rst new file mode 100644 index 000000000..2c54b8463 --- /dev/null +++ b/docs/en/rst/administering/extensions.rst @@ -0,0 +1,18 @@ +.. _installed-extensions-admin: + +Installed Extensions +==================== + +Bugzilla can be enhanced using extensions (see :ref:`extensions`). If an +extension comes with documentation in the appropriate format, and you build +your own copy of the Bugzilla documentation using :file:`makedocs.pl`, then +the documentation for your installed extensions will show up here. + +Your Bugzilla installation has the following extensions available (as of the +last time you compiled the documentation): + +.. toctree:: + :maxdepth: 1 + :glob: + + ../extensions/*/index-admin diff --git a/docs/en/rst/administering/field-values.rst b/docs/en/rst/administering/field-values.rst new file mode 100644 index 000000000..b7380cbdf --- /dev/null +++ b/docs/en/rst/administering/field-values.rst @@ -0,0 +1,45 @@ +.. _field-values: + +Field Values +############ + +Legal values for the operating system, platform, bug priority and +severity, and custom fields of type ``Drop Down`` and +``Multiple-Selection Box`` (see :ref:`custom-fields`), +as well as the list of valid bug statuses and resolutions, can be +customized from the same interface. You can add, edit, disable, and +remove the values that can be used with these fields. + +.. _edit-values-list: + +Viewing/Editing Legal Values +============================ + +Editing legal values requires ``admin`` privileges. +Select "Field Values" from the Administration page. A list of all +fields, both system and Custom, for which legal values +can be edited appears. Click a field name to edit its legal values. + +There is no limit to how many values a field can have, but each value +must be unique to that field. The sortkey is important to display these +values in the desired order. + +When the availability of the values of a custom field is controlled +by another field, you can select from here which value of the other field +must be set for the value of the custom field to appear. + +.. _edit-values-delete: + +Deleting Legal Values +===================== + +Legal values from Custom Fields can be deleted, but only if the +following two conditions are respected: + +#. The value is not set as the default for the field. + +#. No bug is currently using this value. + +If any of these conditions is not respected, the value cannot be deleted. +The only way to delete these values is to reassign bugs to another value +and to set another value as default for the field. diff --git a/docs/en/rst/administering/flags.rst b/docs/en/rst/administering/flags.rst new file mode 100644 index 000000000..0b13690a3 --- /dev/null +++ b/docs/en/rst/administering/flags.rst @@ -0,0 +1,155 @@ +.. _flags-admin: + +Flags +##### + +If you have the :group:`editcomponents` permission, you can +edit Flag Types from the main administration page. Clicking the +: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. + +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: + +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. + +Description + 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 + 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 all + 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* appear and *can* be set for any + products/components 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 cannot select a Component without a Product. If you do so, + Bugzilla will display an error message, even if all your products + have a component by that name. You will also see an error if you + select a Component that does not belong to the selected Product. + + *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``. + However, one component in ``Jet Plane`` is + called ``Pilot``, and 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. + +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 :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". + +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 + cannot target specific users and are open to anyone (called a + request "to the wind" in Bugzilla). 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 :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 ``+``, or is 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 :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 :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 :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 :guilabel:`Delete` link next to +the flag description. + +.. warning:: Once you delete a flag, it is *gone* from + your Bugzilla. All the data for that flag will be deleted. + 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 :guilabel:`active` in the flag Edit form. diff --git a/docs/en/rst/administering/groups.rst b/docs/en/rst/administering/groups.rst new file mode 100644 index 000000000..a14bb689e --- /dev/null +++ b/docs/en/rst/administering/groups.rst @@ -0,0 +1,191 @@ +.. _groups: + +Groups and Security +################### + +Groups allow for separating bugs into logical divisions. +Groups are typically used +to isolate bugs that should only be seen by certain people. For +example, a company might create a different group for each one of its customers +or partners. Group permissions could be set so that each partner or customer would +only have access to their own bugs. Or, groups might be used to create +variable access controls for different departments within an organization. +Another common use of groups is to associate groups with products, +creating isolation and access control on a per-product basis. + +Groups and group behaviors are controlled in several places: + +#. The group configuration page. To view or edit existing groups, or to + create new groups, access the "Groups" link from the "Administration" + page. This section of the manual deals primarily with the aspect of + group controls accessed on this page. + +#. Global configuration parameters. Bugzilla has several parameters + that control the overall default group behavior and restriction + levels. For more information on the parameters that control + group behavior globally, see :ref:`param-group-security`. + +#. Product association with groups. Most of the functionality of groups + and group security is controlled at the product level. Some aspects + of group access controls for products are discussed in this section, + but for more detail see :ref:`product-group-controls`. + +#. Group access for users. See :ref:`users-and-groups` for + details on how users are assigned group access. + +Group permissions are such that if a bug belongs to a group, only members +of that group can see the bug. If a bug is in more than one group, only +members of *all* the groups that the bug is in can see +the bug. For information on granting read-only access to certain people and +full edit access to others, see :ref:`product-group-controls`. + +.. note:: By default, bugs can also be seen by the Assignee, the Reporter, and + everyone on the CC List, regardless of whether or not the bug would + typically be viewable by them. Visibility to the Reporter and CC List can + be overridden (on a per-bug basis) by bringing up the bug, finding the + section that starts with ``Users in the roles selected below...`` + and un-checking the box next to either 'Reporter' or 'CC List' (or both). + +.. _create-groups: + +Creating Groups +=============== + +To create a new group, follow the steps below: + +#. Select the ``Administration`` link in the page footer, + and then select the ``Groups`` link from the + Administration page. + +#. A table of all the existing groups is displayed. Below the table is a + description of all the fields. To create a new group, select the + ``Add Group`` link under the table of existing groups. + +#. There are five fields to fill out. These fields are documented below + the form. Choose a name and description for the group. Decide whether + this group should be used for bugs (in all likelihood this should be + selected). Optionally, choose a regular expression that will + automatically add any matching users to the group, and choose an + icon that will help identify user comments for the group. The regular + expression can be useful, for example, to automatically put all users + from the same company into one group (if the group is for a specific + customer or partner). + + .. note:: If ``User RegExp`` is filled out, users whose email + addresses match the regular expression will automatically be + members of the group as long as their email addresses continue + to match the regular expression. If their email address changes + and no longer matches the regular expression, they will be removed + from the group. Versions 2.16 and older of Bugzilla did not automatically + remove users whose email addresses no longer matched the RegExp. + + .. warning:: If specifying a domain in the regular expression, end + the regexp with a "$". Otherwise, when granting access to + "@mycompany\\.com", access will also be granted to + 'badperson@mycompany.com.cracker.net'. Use the syntax, + '@mycompany\\.com$' for the regular expression. + +#. After the new group is created, it can be edited for additional options. + The "Edit Group" page allows for specifying other groups that should be included + in this group and which groups should be permitted to add and delete + users from this group. For more details, see :ref:`edit-groups`. + +.. _edit-groups: + +Editing Groups and Assigning Group Permissions +============================================== + +To access the "Edit Groups" page, select the +``Administration`` link in the page footer, +and then select the ``Groups`` link from the Administration page. +A table of all the existing groups is displayed. Click on a group name +you wish to edit or control permissions for. + +The "Edit Groups" page contains the same five fields present when +creating a new group. Below that are two additional sections, "Group +Permissions" and "Mass Remove". The "Mass Remove" option simply removes +all users from the group who match the regular expression entered. The +"Group Permissions" section requires further explanation. + +The "Group Permissions" section on the "Edit Groups" page contains four sets +of permissions that control the relationship of this group to other +groups. If the :param:`usevisibilitygroups` parameter is in use (see +:ref:`parameters`) two additional sets of permissions are displayed. +Each set consists of two select boxes. On the left, a select box +with a list of all existing groups. On the right, a select box listing +all groups currently selected for this permission setting (this box will +be empty for new groups). The way these controls allow groups to relate +to one another is called *inheritance*. +Each of the six permissions is described below. + +*Groups That Are a Member of This Group* + Members of any groups selected here will automatically have + membership in this group. In other words, members of any selected + group will inherit membership in this group. + +*Groups That This Group Is a Member Of* + Members of this group will inherit membership to any group + selected here. For example, suppose the group being edited is + an Admin group. If there are two products (Product1 and Product2) + and each product has its + own group (Group1 and Group2), and the Admin group + should have access to both products, + simply select both Group1 and Group2 here. + +*Groups That Can Grant Membership in This Group* + The members of any group selected here will be able add users + to this group, even if they themselves are not in this group. + +*Groups That This Group Can Grant Membership In* + Members of this group can add users to any group selected here, + even if they themselves are not in the selected groups. + +*Groups That Can See This Group* + Members of any selected group can see the users in this group. + This setting is only visible if the :param:`usevisibilitygroups` parameter + is enabled on the Bugzilla Configuration page. See + :ref:`parameters` for information on configuring Bugzilla. + +*Groups That This Group Can See* + Members of this group can see members in any of the selected groups. + This setting is only visible if the :param:`usevisibilitygroups` parameter + is enabled on the the Bugzilla Configuration page. See + :ref:`parameters` for information on configuring Bugzilla. + +.. _users-and-groups: + +Assigning Users to Groups +========================= + +A User can become a member of a group in several ways: + +#. The user can be explicitly placed in the group by editing + the user's profile. This can be done by accessing the "Users" page + from the "Administration" page. Use the search form to find the user + you want to edit group membership for, and click on their email + address in the search results to edit their profile. The profile + page lists all the groups and indicates if the user is a member of + the group either directly or indirectly. More information on indirect + group membership is below. For more details on User Administration, + see :ref:`users`. + +#. The group can include another group of which the user is + a member. This is indicated by square brackets around the checkbox + next to the group name in the user's profile. + See :ref:`edit-groups` for details on group inheritance. + +#. The user's email address can match the regular expression + that has been specified to automatically grant membership to + the group. This is indicated by "\*" around the check box by the + group name in the user's profile. + See :ref:`create-groups` for details on + the regular expression option when creating groups. + +Assigning Group Controls to Products +==================================== + +The primary functionality of groups is derived from the relationship of +groups to products. The concepts around segregating access to bugs with +product group controls can be confusing. For details and examples on this +topic, see :ref:`product-group-controls`. + diff --git a/docs/en/rst/administering/index.rst b/docs/en/rst/administering/index.rst new file mode 100644 index 000000000..c47819323 --- /dev/null +++ b/docs/en/rst/administering/index.rst @@ -0,0 +1,26 @@ +.. _administering: + +==================== +Administration Guide +==================== + +For those with :group:`admin` privileges, Bugzilla can be administered using +the :guilabel:`Administration` link in the header. The administrative +controls are divided into several sections: + +.. toctree:: + :maxdepth: 2 + + parameters + preferences + users + categorization + flags + custom-fields + field-values + workflow + groups + keywords + whining + quips + extensions diff --git a/docs/en/rst/administering/keywords.rst b/docs/en/rst/administering/keywords.rst new file mode 100644 index 000000000..245bcbe4c --- /dev/null +++ b/docs/en/rst/administering/keywords.rst @@ -0,0 +1,16 @@ +.. _keywords: + +Keywords +######## + +The administrator can define keywords which can be used to tag and +categorise bugs. For example, the keyword "regression" is commonly used. +A company might have a policy stating all regressions +must be fixed by the next release—this keyword can make tracking those +bugs much easier. Keywords are global, rather than per product. + +Keywords can be created, edited, or deleted by clicking the "Keywords" +link in the admin page. There are two fields for each keyword—the keyword +itself and a brief description. Currently keywords cannot be marked obsolete +to prevent future usage. + diff --git a/docs/en/rst/administering/parameters.rst b/docs/en/rst/administering/parameters.rst new file mode 100644 index 000000000..7f376bbf2 --- /dev/null +++ b/docs/en/rst/administering/parameters.rst @@ -0,0 +1,794 @@ +.. _parameters: + +Parameters +########## + +Bugzilla is configured by changing various parameters, accessed +from the :guilabel:`Parameters` link, which is found on the Administration +page. The parameters are divided into several categories, +accessed via the menu on the left. + +.. _param-required-settings: + +Required Settings +================= + +The core required parameters for any Bugzilla installation are set +here. :param:`urlbase` is always required; the other parameters should be +set, or it must be explicitly decided not to +set them, before the new Bugzilla installation starts to be used. + +urlbase + Defines the fully qualified domain name and web + server path to this Bugzilla installation. + For example, if the Bugzilla query page is + :file:`http://www.foo.com/bugzilla/query.cgi`, + the :param:`urlbase` should be set + to :paramval:`http://www.foo.com/bugzilla/`. + +ssl_redirect + If enabled, Bugzilla will force HTTPS (SSL) connections, by + automatically redirecting any users who try to use a non-SSL + connection. Also, when this is enabled, Bugzilla will send out links + using :param:`sslbase` in emails instead of :param:`urlbase`. + +sslbase + Defines the fully qualified domain name and web + server path for HTTPS (SSL) connections to this Bugzilla installation. + For example, if the Bugzilla main page is + :file:`https://www.foo.com/bugzilla/index.cgi`, + the :param:`sslbase` should be set + to :paramval:`https://www.foo.com/bugzilla/`. + +cookiepath + Defines a path, relative to the web document root, that Bugzilla + cookies will be restricted to. For example, if the + :param:`urlbase` is set to + :file:`http://www.foo.com/bugzilla/`, the + :param:`cookiepath` should be set to + :paramval:`/bugzilla/`. Setting it to :paramval:`/` will allow all sites + served by this web server or virtual host to read Bugzilla cookies. + +.. _param-general: + +General +======= + +maintainer + Email address of the person + responsible for maintaining this Bugzilla installation. + The address need not be that of a valid Bugzilla account. + +utf8 + Use UTF-8 (Unicode) encoding for all text in Bugzilla. Installations where + this parameter is set to :paramval:`off` should set it to :paramval:`on` only + after the data has been converted from existing legacy character + encodings to UTF-8, using the + :file:`contrib/recode.pl` script. + + .. note:: If you turn this parameter from :paramval:`off` to :paramval:`on`, + you must re-run :file:`checksetup.pl` immediately afterward. + +shutdownhtml + If there is any text in this field, this Bugzilla installation will + be completely disabled and this text will appear instead of all + Bugzilla pages for all users, including Admins. Used in the event + of site maintenance or outage situations. + +announcehtml + Any text in this field will be displayed at the top of every HTML + page in this Bugzilla installation. The text is not wrapped in any + tags. For best results, wrap the text in a ``
`` + tag. Any style attributes from the CSS can be applied. For example, + to make the text green inside of a red box, add ``id=message`` + to the ``
`` tag. + +upgrade_notification + Enable or disable a notification on the homepage of this Bugzilla + installation when a newer version of Bugzilla is available. This + notification is only visible to administrators. Choose :paramval:`disabled` + to turn off the notification. Otherwise, choose which version of + Bugzilla you want to be notified about: :paramval:`development_snapshot` is the + latest release from the master branch, :paramval:`latest_stable_release` is the most + recent release available on the most recent stable branch, and + :paramval:`stable_branch_release` is the most recent release on the branch + this installation is based on. + +.. _param-administrative-policies: + +Administrative Policies +======================= + +This page contains parameters for basic administrative functions. +Options include whether to allow the deletion of bugs and users, +and whether to allow users to change their email address. + +allowbugdeletion + The pages to edit products and components can delete all associated bugs when you delete a product (or component). Since that is a pretty scary idea, you have to turn on this option before any such deletions will ever happen. + +allowemailchange + Users can change their own email address through the preferences. Note that the change is validated by emailing both addresses, so switching this option on will not let users use an invalid address. + +allowuserdeletion + The user editing pages are capable of letting you delete user accounts. Bugzilla will issue a warning in case you'd run into inconsistencies when you're about to do so, but such deletions still remain scary. So, you have to turn on this option before any such deletions will ever happen. + +last_visit_keep_days + This option controls how many days Bugzilla will remember that users have visited specific bugs. + +.. _param-user-authentication: + +User Authentication +=================== + +This page contains the settings that control how this Bugzilla +installation will do its authentication. Choose what authentication +mechanism to use (the Bugzilla database, or an external source such +as LDAP), and set basic behavioral parameters. For example, choose +whether to require users to login to browse bugs, the management +of authentication cookies, and the regular expression used to +validate email addresses. Some parameters are highlighted below. + +auth_env_id + Environment variable used by external authentication system to store a unique identifier for each user. Leave it blank if there isn't one or if this method of authentication is not being used. + +auth_env_email + Environment variable used by external authentication system to store each user's email address. This is a required field for environmental authentication. Leave it blank if you are not going to use this feature. + +auth_env_realname + Environment variable used by external authentication system to store the user's real name. Leave it blank if there isn't one or if this method of authentication is not being used. + +user_info_class + Mechanism(s) to be used for gathering a user's login information. More than one may be selected. If the first one returns nothing, the second is tried, and so on. The types are: + + * :paramval:`CGI`: asks for username and password via CGI form interface. + * :paramval:`Env`: info for a pre-authenticated user is passed in system environment variables. + +user_verify_class + Mechanism(s) to be used for verifying (authenticating) information gathered by user_info_class. More than one may be selected. If the first one cannot find the user, the second is tried, and so on. The types are: + + * :paramval:`DB`: Bugzilla's built-in authentication. This is the most common choice. + * :paramval:`RADIUS`: RADIUS authentication using a RADIUS server. Using this method requires additional parameters to be set. Please see :ref:`param-radius` for more information. + * :paramval:`LDAP`: LDAP authentication using an LDAP server. Using this method requires additional parameters to be set. Please see :ref:`param-ldap` for more information. + +rememberlogin + Controls management of session cookies. + + * :paramval:`on` - Session cookies never expire (the user has to login only once per browser). + * :paramval:`off` - Session cookies last until the users session ends (the user will have to login in each new browser session). + * :paramval:`defaulton`/:paramval:`defaultoff` - Default behavior as described above, but user can choose whether Bugzilla will remember their login or not. + +requirelogin + If this option is set, all access to the system beyond the front page will require a login. No anonymous users will be permitted. + +webservice_email_filter + Filter email addresses returned by the WebService API depending on if the user is logged in or not. This works similarly to how the web UI currently filters email addresses. If requirelogin is enabled, then this parameter has no effect as users must be logged in to use Bugzilla anyway. + +emailregexp + Defines the regular expression used to validate email addresses + used for login names. The default attempts to match fully + qualified email addresses (i.e. 'user\@example.com') in a slightly + more restrictive way than what is allowed in RFC 2822. + Another popular value to put here is :paramval:`^[^@]+`, which means 'local usernames, no @ allowed.' + +emailregexpdesc + This description is shown to the user to explain which email addresses are allowed by the :param:`emailregexp` param. + +emailsuffix + This is a string to append to any email addresses when actually sending mail to that address. It is useful if you have changed the :param:`emailregexp` param to only allow local usernames, but you want the mail to be delivered to username\@my.local.hostname. + +createemailregexp + This defines the (case-insensitive) regexp to use for email addresses that are permitted to self-register. The default (:paramval:`.*`) permits any account matching the emailregexp to be created. If this parameter is left blank, no users will be permitted to create their own accounts and all accounts will have to be created by an administrator. + +password_complexity + Set the complexity required for passwords. In all cases must the passwords be at least 6 characters long. + + * :paramval:`no_constraints` - No complexity required. + * :paramval:`mixed_letters` - Passwords must contain at least one UPPER and one lower case letter. + * :paramval:`letters_numbers` - Passwords must contain at least one UPPER and one lower case letter and a number. + * :paramval:`letters_numbers_specialchars` - Passwords must contain at least one letter, a number and a special character. + +password_check_on_login + If set, Bugzilla will check that the password meets the current complexity rules and minimum length requirements when the user logs into the Bugzilla web interface. If it doesn't, the user would not be able to log in, and will receive a message to reset their password. + +.. _param-attachments: + +Attachments +=========== + +This page allows for setting restrictions and other parameters +regarding attachments to bugs. For example, control size limitations +and whether to allow pointing to external files via a URI. + +allow_attachment_display + If this option is on, users will be able to view attachments from their browser, if their browser supports the attachment's MIME type. If this option is off, users are forced to download attachments, even if the browser is able to display them. + + If you do not trust your users (e.g. if your Bugzilla is public), you should either leave this option off, or configure and set the :param:`attachment_base` parameter (see below). Untrusted users may upload attachments that could be potentially damaging if viewed directly in the browser. + +attachment_base + When the :param:`allow_attachment_display` parameter is on, it is possible for a malicious attachment to steal your cookies or perform an attack on Bugzilla using your credentials. + + If you would like additional security on attachments to avoid this, set this parameter to an alternate URL for your Bugzilla that is not the same as :param:`urlbase` or :param:`sslbase`. That is, a different domain name that resolves to this exact same Bugzilla installation. + + Note that if you have set the :param:`cookiedomain` parameter, you should set :param:`attachment_base` to use a domain that would not be matched by :param:`cookiedomain`. + + For added security, you can insert ``%bugid%`` into the URL, which will be replaced with the ID of the current bug that the attachment is on, when you access an attachment. This will limit attachments to accessing only other attachments on the same bug. Remember, though, that all those possible domain names (such as 1234.your.domain.com) must point to this same Bugzilla instance. To set this up you need to investigate wildcard DNS. + +allow_attachment_deletion + If this option is on, administrators will be able to delete the contents + of attachments (i.e. replace the attached file with a 0 byte file), + leaving only the metadata. + +maxattachmentsize + The maximum size (in kilobytes) of attachments to be stored in the database. If a file larger than this size is attached to a bug, Bugzilla will look at the :param:`maxlocalattachment` parameter to determine if the file can be stored locally on the web server. If the file size exceeds both limits, then the attachment is rejected. Setting both parameters to 0 will prevent attaching files to bugs. + + Some databases have default limits which prevent storing larger attachments in the database. E.g. MySQL has a parameter called `max_allowed_packet `_, whose default varies by distribution. Setting :param:`maxattachmentsize` higher than your current setting for this value will produce an error. + +maxlocalattachment + The maximum size (in megabytes) of attachments to be stored locally on the web server. If set to a value lower than the :param:`maxattachmentsize` parameter, attachments will never be kept on the local filesystem. + + Whether you use this feature or not depends on your environment. Reasons to store some or all attachments as files might include poor database performance for large binary blobs, ease of backup/restore/browsing, or even filesystem-level deduplication support. However, you need to be aware of any limits on how much data your webserver environment can store. If in doubt, leave the value at 0. + + Note that changing this value does not affect any already-submitted attachments. + +.. _param-bug-change-policies: + +Bug Change Policies +=================== + +Set policy on default behavior for bug change events. For example, +choose which status to set a bug to when it is marked as a duplicate, +and choose whether to allow bug reporters to set the priority or +target milestone. Also allows for configuration of what changes +should require the user to make a comment, described below. + +duplicate_or_move_bug_status + When a bug is marked as a duplicate of another one, use this bug status. + +letsubmitterchoosepriority + If this is on, then people submitting bugs can choose an initial priority for that bug. If off, then all bugs initially have the default priority selected here. + +letsubmitterchoosemilestone + If this is on, then people submitting bugs can choose the Target Milestone for that bug. If off, then all bugs initially have the default milestone for the product being filed in. + +musthavemilestoneonaccept + If you are using Target Milestone, do you want to require that the milestone be set in order for a user to set a bug's status to IN_PROGRESS? + +commenton* + All these fields allow you to dictate what changes can pass + without comment and which must have a comment from the + person who changed them. Often, administrators will allow + users to add themselves to the CC list, accept bugs, or + change the Status Whiteboard without adding a comment as to + their reasons for the change, yet require that most other + changes come with an explanation. + Set the "commenton" options according to your site policy. It + is a wise idea to require comments when users resolve, reassign, or + reopen bugs at the very least. + + .. note:: It is generally far better to require a developer comment + when resolving bugs than not. Few things are more annoying to bug + database users than having a developer mark a bug "fixed" without + any comment as to what the fix was (or even that it was truly + fixed!) + +noresolveonopenblockers + This option will prevent users from resolving bugs as FIXED if + they have unresolved dependencies. Only the FIXED resolution + is affected. Users will be still able to resolve bugs to + resolutions other than FIXED if they have unresolved dependent + bugs. + +.. _param-bugfields: + +Bug Fields +========== + +The parameters in this section determine the default settings of +several Bugzilla fields for new bugs and whether +certain fields are used. For example, choose whether to use the +:field:`Target Milestone` field or the :field:`Status Whiteboard` field. + +useclassification + If this is on, Bugzilla will associate each product with a specific + classification. But you must have :group:`editclassification` permissions + enabled in order to edit classifications. + +usetargetmilestone + Do you wish to use the :field:`Target Milestone` field? + +useqacontact + This allows you to define an email address for each component, + in addition to that of the default assignee, that will be sent + carbon copies of incoming bugs. + +usestatuswhiteboard + This defines whether you wish to have a free-form, overwritable field + associated with each bug. The advantage of the :field:`Status Whiteboard` + is that it can be deleted or modified with ease and provides an + easily searchable field for indexing bugs that have some trait in + common. + +use_see_also + Do you wish to use the :field:`See Also` field? It allows you mark bugs + in other bug tracker installations as being related. Disabling this field + prevents addition of new relationships, but existing ones will continue to + appear. + +defaultpriority + This is the priority that newly entered bugs are set to. + +defaultseverity + This is the severity that newly entered bugs are set to. + +defaultplatform + This is the platform that is preselected on the bug entry form. + You can leave this empty; Bugzilla will then use the platform that the + browser is running on as the default. + +defaultopsys + This is the operating system that is preselected on the bug entry form. + You can leave this empty; Bugzilla will then use the operating system + that the browser reports to be running on as the default. + +collapsed_comment_tags + A comma-separated list of tags which, when applied to comments, will + cause them to be collapsed by default. + +.. _param-dependency-graphs: + +Graphs +====== + +Bugzilla can draw graphs of bug-dependency relationships, using a tool called +:file:`dot` (from the `GraphViz project `_) or a web +service called Web Dot. This page allows you to set the location of the binary +or service. If no Web Dot server or binary is specified, then dependency +graphs will be disabled. + +webdotbase + You may set this parameter to any of the following: + + * A complete file path to :command:`dot` (part of GraphViz), which will + generate the graphs locally. + * A URL prefix pointing to an installation of the Web Dot package, which + will generate the graphs remotely. + * A blank value, which will disable dependency graphing. + + The default value is blank. We recommend using a local install of + :file:`dot`. If you change this value to a web service, make certain that + the Web Dot server can read files from your Web Dot directory. On Apache + you do this by editing the :file:`.htaccess` file; for other systems the + needed measures may vary. You can run :command:`checksetup.pl` to + recreate the :file:`.htaccess` file if it has been lost. + +font_file + You can specify the full path to a TrueType font file which will be used + to display text (labels, legends, ...) in charts and graphical reports. + To support as many languages as possible, we recommend to specify a + TrueType font such as Unifont which supports all printable characters in + the Basic Multilingual Plane. If you leave this parameter empty, a default + font will be used, but its support is limited to English characters only + and so other characters will be displayed incorrectly. + +.. _param-group-security: + +Group Security +============== + +Bugzilla allows for the creation of different groups, with the +ability to restrict the visibility of bugs in a group to a set of +specific users. Specific products can also be associated with +groups, and users restricted to only see products in their groups. +Several parameters are described in more detail below. Most of the +configuration of groups and their relationship to products is done +on the :guilabel:`Groups` and :guilabel:`Product` pages of the +:guilabel:`Administration` area. +The options on this page control global default behavior. +For more information on Groups and Group Security, see +:ref:`groups`. + +makeproductgroups + Determines whether or not to automatically create groups + when new products are created. If this is on, the groups will be + used for querying bugs. + + .. todo:: This is spectacularly unclear. I have no idea what makeproductgroups + does - can someone explain it to me? Convert this item into a bug on checkin. + +chartgroup + The name of the group of users who can use the 'New Charts' feature. Administrators should ensure that the public categories and series definitions do not divulge confidential information before enabling this for an untrusted population. If left blank, no users will be able to use New Charts. + +insidergroup + The name of the group of users who can see/change private comments and attachments. + +timetrackinggroup + The name of the group of users who can see/change time tracking information. + +querysharegroup + The name of the group of users who are allowed to share saved + searches with one another. For more information on using + saved searches, see :ref:`saved-searches`. + +comment_taggers_group + The name of the group of users who can tag comments. Setting this to empty disables comment tagging. + +debug_group + The name of the group of users who can view the actual SQL query generated when viewing bug lists and reports. Do not expose this information to untrusted users. + +usevisibilitygroups + If selected, user visibility will be restricted to members of + groups, as selected in the group configuration settings. + Each user-defined group can be allowed to see members of selected + other groups. + For details on configuring groups (including the visibility + restrictions) see :ref:`edit-groups`. + +or_groups + Define the visibility of a bug which is in multiple groups. If + this is on (recommended), a user only needs to be a member of one + of the bug's groups in order to view it. If it is off, a user + needs to be a member of all the bug's groups. Note that in either + case, a user's role on the bug (e.g. reporter), if any, may also + affect their permissions. + +.. _param-ldap: + +LDAP +==== + +LDAP authentication is a module for Bugzilla's plugin +authentication architecture. This page contains all the parameters +necessary to configure Bugzilla for use with LDAP authentication. + +The existing authentication +scheme for Bugzilla uses email addresses as the primary user ID and a +password to authenticate that user. All places within Bugzilla that +require a user ID (e.g assigning a bug) use the email +address. The LDAP authentication builds on top of this scheme, rather +than replacing it. The initial log-in is done with a username and +password for the LDAP directory. Bugzilla tries to bind to LDAP using +those credentials and, if successful, tries to map this account to a +Bugzilla account. If an LDAP mail attribute is defined, the value of this +attribute is used; otherwise, the :param:`emailsuffix` parameter is appended to +the LDAP username to form a full email address. If an account for this address +already exists in the Bugzilla installation, it will log in to that account. +If no account for that email address exists, one is created at the time +of login. (In this case, Bugzilla will attempt to use the "displayName" +or "cn" attribute to determine the user's full name.) After +authentication, all other user-related tasks are still handled by email +address, not LDAP username. For example, bugs are still assigned by +email address and users are still queried by email address. + +.. warning:: Because the Bugzilla account is not created until the first time + a user logs in, a user who has not yet logged is unknown to Bugzilla. + This means they cannot be used as an assignee or QA contact (default or + 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`. + +Parameters required to use LDAP Authentication: + +user_verify_class (in the Authentication section) + If you want to list :paramval:`LDAP` here, + make sure to have set up the other parameters listed below. + Unless you have other (working) authentication methods listed as + 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.json` and set :param:`user_verify_class` to + :paramval:`DB`. + +LDAPserver + This parameter should be set to the name (and optionally the + port) of your LDAP server. If no port is specified, it assumes + the default LDAP port of 389. + For example: :paramval:`ldap.company.com` + or :paramval:`ldap.company.com:3268` + You can also specify a LDAP URI, so as to use other + protocols, such as LDAPS or LDAPI. If the port was not specified in + the URI, the default is either 389 or 636 for 'LDAP' and 'LDAPS' + schemes respectively. + + .. note:: In order to use SSL with LDAP, specify a URI with "ldaps://". + This will force the use of SSL over port 636. + For example, normal LDAP :paramval:`ldap://ldap.company.com`, LDAP over + SSL :paramval:`ldaps://ldap.company.com`, or LDAP over a UNIX + domain socket :paramval:`ldapi://%2fvar%2flib%2fldap_sock`. + +LDAPstarttls + Whether to require encrypted communication once a normal LDAP connection + is achieved with the server. + +LDAPbinddn [Optional] + Some LDAP servers will not allow an anonymous bind to search + the directory. If this is the case with your configuration you + should set the :param:`LDAPbinddn` parameter to the user account Bugzilla + should use instead of the anonymous bind. + Ex. :paramval:`cn=default,cn=user:password` + +LDAPBaseDN + The location in + your LDAP tree that you would like to search for email addresses. + Your uids should be unique under the DN specified here. + Ex. :paramval:`ou=People,o=Company` + +LDAPuidattribute + The attribute + which contains the unique UID of your users. The value retrieved + from this attribute will be used when attempting to bind as the + user to confirm their password. + Ex. :paramval:`uid` + +LDAPmailattribute + The name of the + attribute which contains the email address your users will enter + into the Bugzilla login boxes. + Ex. :paramval:`mail` + +LDAPfilter + LDAP filter to AND with the LDAPuidattribute for filtering the list of + valid users. + +.. _param-radius: + +RADIUS +====== + +RADIUS authentication is a module for Bugzilla's plugin +authentication architecture. This page contains all the parameters +necessary for configuring Bugzilla to use RADIUS authentication. + +.. note:: Most caveats that apply to LDAP authentication apply to RADIUS + authentication as well. See :ref:`param-ldap` for details. + +Parameters required to use RADIUS Authentication: + +user_verify_class (in the Authentication section) + If you want to list :paramval:`RADIUS` here, + make sure to have set up the other parameters listed below. + Unless you have other (working) authentication methods listed as + 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.json` and set :param:`user_verify_class` to + :paramval:`DB`. + +RADIUS_server + The name (and optionally the port) of your RADIUS server. + +RADIUS_secret + The RADIUS server's secret. + +RADIUS_NAS_IP + The NAS-IP-Address attribute to be used when exchanging data with your + RADIUS server. If unspecified, 127.0.0.1 will be used. + +RADIUS_email_suffix + Bugzilla needs an email address for each user account. + Therefore, it needs to determine the email address corresponding + to a RADIUS user. + Bugzilla offers only a simple way to do this: it can concatenate + a suffix to the RADIUS user name to convert it into an email + address. + You can specify this suffix in the :param:`RADIUS_email_suffix` parameter. + If this simple solution does not work for you, you'll + probably need to modify + :file:`Bugzilla/Auth/Verify/RADIUS.pm` to match your + requirements. + +.. _param-email: + +Email +===== + +This page contains all of the parameters for configuring how +Bugzilla deals with the email notifications it sends. See below +for a summary of important options. + +mail_delivery_method + This is used to specify how email is sent, or if it is sent at + all. There are several options included for different MTAs, + along with two additional options that disable email sending. + :paramval:`Test` does not send mail, but instead saves it in + :file:`data/mailer.testfile` for later review. + :paramval:`None` disables email sending entirely. + +mailfrom + This is the email address that will appear in the "From" field + of all emails sent by this Bugzilla installation. Some email + servers require mail to be from a valid email address; therefore, + it is recommended to choose a valid email address here. + +use_mailer_queue + In a large Bugzilla installation, updating bugs can be very slow because Bugzilla sends all email at once. If you enable this parameter, Bugzilla will queue all mail and then send it in the background. This requires that you have installed certain Perl modules (as listed by :file:`checksetup.pl` for this feature), and that you are running the :file:`jobqueue.pl` daemon (otherwise your mail won't get sent). This affects all mail sent by Bugzilla, not just bug updates. + +smtpserver + The SMTP server address, if the :param:`mail_delivery_method` + parameter is set to :paramval:`SMTP`. Use :paramval:`localhost` if you have a local MTA + running; otherwise, use a remote SMTP server. Append ":" and the port + number if a non-default port is needed. + +smtp_username + Username to use for SASL authentication to the SMTP server. Leave + this parameter empty if your server does not require authentication. + +smtp_password + Password to use for SASL authentication to the SMTP server. This + parameter will be ignored if the :param:`smtp_username` + parameter is left empty. + +smtp_ssl + Enable SSL support for connection to the SMTP server. + +smtp_debug + This parameter allows you to enable detailed debugging output. + Log messages are printed the web server's error log. + +whinedays + 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 :ref:`whining cron job ` described + in the installation instructions, or set this value to "0" (never whine). + +globalwatchers + This allows you to define specific users who will + receive notification each time any new bug in entered, or when + any existing bug changes, subject to the normal groupset + permissions. It may be useful for sending notifications to a + mailing list, for instance. + +.. _param-querydefaults: + +Query Defaults +============== + +This page controls the default behavior of Bugzilla in regards to +several aspects of querying bugs. Options include what the default +query options are, what the "My Bugs" page returns, whether users +can freely add bugs to the quip list, and how many duplicate bugs are +needed to add a bug to the "most frequently reported" list. + +quip_list_entry_control + Controls how easily users can add entries to the quip list. + + * :paramval:`open` - Users may freely add to the quip list, and their entries will immediately be available for viewing. + * :paramval:`moderated` - Quips can be entered but need to be approved by a moderator before they will be shown. + * :paramval:`closed` - No new additions to the quips list are allowed. + +mybugstemplate + This is the URL to use to bring up a simple 'all of my bugs' list + for a user. %userid% will get replaced with the login name of a + user. Special characters must be URL encoded. + +defaultquery + This is the default query that initially comes up when you access + the advanced query page. It's in URL-parameter format. + +search_allow_no_criteria + When turned off, a query must have some criteria specified to limit the number of bugs returned to the user. When turned on, a user is allowed to run a query with no criteria and get all bugs in the entire installation that they can see. Turning this parameter on is not recommended on large installations. + +default_search_limit + By default, Bugzilla limits searches done in the web interface to returning only this many results, for performance reasons. (This only affects the HTML format of search results—CSV, XML, and other formats are exempted.) Users can click a link on the search result page to see all the results. + + Usually you should not have to change this—the default value should be acceptable for most installations. + +max_search_results + The maximum number of bugs that a search can ever return. Tabular and graphical reports are exempted from this limit, however. + + + +.. _param-shadowdatabase: + +Shadow Database +=============== + +This page controls whether a shadow database is used. If your Bugzilla is +not large, you will not need these options. + +A standard large database setup involves a single master server and a pool of +read-only slaves (which Bugzilla calls the "shadowdb"). Queries which are not +updating data can be directed to the slave pool, removing the load/locking +from the master, freeing it up to handle writes. Bugzilla will switch to the +shadowdb when it knows it doesn't need to update the database (e.g. when +searching, or displaying a bug to a not-logged-in user). + +Bugzilla does not make sure the shadowdb is kept up to date, so, if you use +one, you will need to set up replication in your database server. + +If your shadowdb is on a different machine, specify :param:`shadowdbhost` +and :param:`shadowdbport`. If it's on the same machine, specify +:param:`shadowdbsock`. + +shadowdbhost + The host the shadow database is on. + +shadowdbport + The port the shadow database is on. + +shadowdbsock + The socket used to connect to the shadow database, if the host is the + local machine. + +shadowdb + The database name of the shadow database. + +.. _admin-memcached: + +Memcached +========= + +memcached_servers + If this option is set, Bugzilla will integrate with `Memcached + `_. Specify one or more servers, separated by + spaces, using hostname:port notation (for example: + :paramval:`127.0.0.1:11211`). + +memcached_namespace + Specify a string to prefix each key on Memcached. + +.. _admin-usermatching: + +User Matching +============= + +The settings on this page control how users are selected and queried +when adding a user to a bug. For example, users need to be selected +when assigning the bug, adding to the CC list, or +selecting a QA contact. With the :param:`usemenuforusers` parameter, it is +possible to configure Bugzilla to +display a list of users in the fields instead of an empty text field. +If users are selected via a text box, this page also +contains parameters for how user names can be queried and matched +when entered. + +usemenuforusers + If this option is set, Bugzilla will offer you a list to select from (instead of a text entry field) where a user needs to be selected. This option should not be enabled on sites where there are a large number of users. + +ajax_user_autocompletion + If this option is set, typing characters in a certain user fields + will display a list of matches that can be selected from. It is + recommended to only turn this on if you are using mod_perl; + otherwise, the response will be irritatingly slow. + +maxusermatches + Provide no more than this many matches when a user is searched for. + If set to '1', no users will be displayed on ambiguous + matches. This is useful for user-privacy purposes. A value of zero + means no limit. + +confirmuniqueusermatch + Whether a confirmation screen should be displayed when only one user matches a search entry. + +.. _admin-advanced: + +Advanced +======== + +cookiedomain + Defines the domain for Bugzilla cookies. This is typically left blank. + If there are multiple hostnames that point to the same webserver, which + require the same cookie, then this parameter can be utilized. For + example, If your website is at + ``https://bugzilla.example.com/``, setting this to + :paramval:`.example.com/` will also allow + ``attachments.example.com/`` to access Bugzilla cookies. + +inbound_proxies + When inbound traffic to Bugzilla goes through a proxy, Bugzilla thinks that the IP address of the proxy is the IP address of every single user. If you enter a comma-separated list of IPs in this parameter, then Bugzilla will trust any ``X-Forwarded-For`` header sent from those IPs, and use the value of that header as the end user's IP address. + +proxy_url + If this Bugzilla installation is behind a proxy, enter the proxy + information here to enable Bugzilla to access the Internet. Bugzilla + requires Internet access to utilize the + :param:`upgrade_notification` parameter. If the + proxy requires authentication, use the syntax: + :paramval:`http://user:pass@proxy_url/`. + +strict_transport_security + Enables the sending of the Strict-Transport-Security header along with HTTP responses on SSL connections. This adds greater security to your SSL connections by forcing the browser to always access your domain over SSL and never accept an invalid certificate. However, it should only be used if you have the :param:`ssl_redirect` parameter turned on, Bugzilla is the only thing running on its domain (i.e., your :param:`urlbase` is something like :paramval:`http://bugzilla.example.com/`), and you never plan to stop supporting SSL. + + * :paramval:`off` - Don't send the Strict-Transport-Security header with requests. + * :paramval:`this_domain_only` - Send the Strict-Transport-Security header with all requests, but only support it for the current domain. + * :paramval:`include_subdomains` - Send the Strict-Transport-Security header along with the includeSubDomains flag, which will apply the security change to all subdomains. This is especially useful when combined with an :param:`attachment_base` that exists as (a) subdomain(s) under the main Bugzilla domain. diff --git a/docs/en/rst/administering/preferences.rst b/docs/en/rst/administering/preferences.rst new file mode 100644 index 000000000..0b89c7b13 --- /dev/null +++ b/docs/en/rst/administering/preferences.rst @@ -0,0 +1,10 @@ +.. _default-preferences: + +Default Preferences +################### + +Each user of Bugzilla can set certain preferences about how they want +Bugzilla to behave. Here, you can say whether or not each of the possible +preferences is available to the user and, if it is, what the default value +is. + diff --git a/docs/en/rst/administering/quips.rst b/docs/en/rst/administering/quips.rst new file mode 100644 index 000000000..789304a33 --- /dev/null +++ b/docs/en/rst/administering/quips.rst @@ -0,0 +1,38 @@ +.. _quips: + +Quips +##### + +Quips are small user-defined messages (often quotes or witty sayings) that +can be configured to appear at the top of search results. Each Bugzilla +installation has its own specific quips. Whenever a quip needs to be +displayed, a random selection is made from the pool of already existing quips. + +Quip submission is controlled by :param:`quip_list_entry_control` +parameter. It has several possible values: open, moderated, or closed. +In order to enable quips approval you need to set this parameter to +"moderated". In this way, users are free to submit quips for addition, +but an administrator must explicitly approve them before they are +actually used. + +In order to see the user interface for the quips, you can +click on a quip when it is displayed together with the search +results. You can also go directly to the quips.cgi URL +(prefixed with the usual web location of the Bugzilla installation). +Once the quip interface is displayed, the "view and edit the whole +quip list" link takes you to the quips administration page, which +lists all quips available in the database. + +Next to each quip there is a checkbox, under the +"Approved" column. Quips that have this checkbox checked are +already approved and will appear next to the search results. +The ones that have it unchecked are still preserved in the +database but will not appear on search results pages. +User submitted quips have initially the checkbox unchecked. + +Also, there is a delete link next to each quip, +which can be used in order to permanently delete a quip. + +Display of quips is controlled by the *display_quips* +user preference. Possible values are "on" and "off". + diff --git a/docs/en/rst/administering/users.rst b/docs/en/rst/administering/users.rst new file mode 100644 index 000000000..b8657e5d9 --- /dev/null +++ b/docs/en/rst/administering/users.rst @@ -0,0 +1,244 @@ +.. _users: + +Users +##### + +.. _defaultuser: + +Creating Admin Users +==================== + +When you first run checksetup.pl after installing Bugzilla, it will +prompt you for the username (email address) and password for the first +admin user. If for some reason you delete all the admin users, +re-running checksetup.pl will again prompt you for a username and +password and make a new admin. + +If you wish to add more administrative users, add them to the "admin" group. + +.. _user-account-search: + +Searching For Users +=================== + +If you have ``editusers`` privileges or if you are allowed +to grant privileges for some groups, the :guilabel:`Users` link +will appear in the Administration page. + +The first screen is a search form to search for existing user +accounts. You can run searches based either on the user ID, real +name or login name (i.e. the email address, or just the first part +of the email address if the :param:`emailsuffix` parameter is set). +The search can be conducted +in different ways using the listbox to the right of the text entry +box. You can match by case-insensitive substring (the default), +regular expression, a *reverse* regular expression +match (which finds every user name which does NOT match the regular +expression), or the exact string if you know exactly who you are +looking for. The search can be restricted to users who are in a +specific group. By default, the restriction is turned off. + +The search returns a list of +users matching your criteria. User properties can be edited by clicking +the login name. The Account History of a user can be viewed by clicking +the "View" link in the Account History column. The Account History +displays changes that have been made to the user account, the time of +the change and the user who made the change. For example, the Account +History page will display details of when a user was added or removed +from a group. + +.. _modifyusers: + +Modifying Users +=============== + +Once you have found your user, you can change the following +fields: + +- *Login Name*: + This is generally the user's full email address. However, if you + have are using the :param:`emailsuffix` parameter, this may + just be the user's login name. Unless you turn off the + :param:`allowemailchange` parameter, users can change their + login names themselves (to any valid email address). + +- *Real Name*: The user's real name. Note that + Bugzilla does not require this to create an account. + +- *Password*: + You can change the user's password here. Users can automatically + request a new password, so you shouldn't need to do this often. + If you want to disable an account, see Disable Text below. + +- *Bugmail Disabled*: + Mark this checkbox to disable bugmail and whinemail completely + for this account. This checkbox replaces the data/nomail file + which existed in older versions of Bugzilla. + +- *Disable Text*: + If you type anything in this box, including just a space, the + user is prevented from logging in and from making any changes to + bugs via the web interface. + The HTML you type in this box is presented to the user when + they attempt to perform these actions and should explain + why the account was disabled. + Users with disabled accounts will continue to receive + mail from Bugzilla; furthermore, they will not be able + to log in themselves to change their own preferences and + stop it. If you want an account (disabled or active) to + stop receiving mail, simply check the + ``Bugmail Disabled`` checkbox above. + + .. note:: Even users whose accounts have been disabled can still + submit bugs via the email gateway, if one exists. + The email gateway should *not* be + enabled for secure installations of Bugzilla. + + .. warning:: Don't disable all the administrator accounts! + +- **: + If you have created some groups, e.g. "securitysensitive", then + checkboxes will appear here to allow you to add users to, or + remove them from, these groups. The first checkbox gives the + user the ability to add and remove other users as members of + this group. The second checkbox adds the user himself as a member + of the group. + +- *canconfirm*: + This field is only used if you have enabled the "unconfirmed" + status. If you enable this for a user, + that user can then move bugs from "Unconfirmed" to a "Confirmed" + status (e.g.: "New" status). + +- *creategroups*: + This option will allow a user to create and destroy groups in + Bugzilla. + +- *editbugs*: + Unless a user has this bit set, they can only edit those bugs + for which they are the assignee or the reporter. Even if this + option is unchecked, users can still add comments to bugs. + +- *editcomponents*: + This flag allows a user to create new products and components, + modify existing products and components, and destroy those that have + no bugs associated with them. If a product or component has bugs + associated with it, those bugs must be moved to a different product + or component before Bugzilla will allow them to be destroyed. + +- *editkeywords*: + If you use Bugzilla's keyword functionality, enabling this + feature allows a user to create and destroy keywords. A keyword + must be removed from any bugs upon which it is currently set + before it can be destroyed. + +- *editusers*: + This flag allows a user to do what you're doing right now: edit + other users. This will allow those with the right to do so to + remove administrator privileges from other users or grant them to + themselves. Enable with care. + +- *tweakparams*: + This flag allows a user to change Bugzilla's Params + (using :file:`editparams.cgi`.) + +- **: + This allows an administrator to specify the products + in which a user can see bugs. If you turn on the + :param:`makeproductgroups` parameter in + the Group Security Panel in the Parameters page, + then Bugzilla creates one group per product (at the time you create + the product), and this group has exactly the same name as the + product itself. Note that for products that already exist when + the parameter is turned on, the corresponding group will not be + created. The user must still have the :group:`editbugs` + privilege to edit bugs in these products. + +.. _createnewusers: + +Creating New Users +================== + +.. _self-registration: + +Self-Registration +----------------- + +By default, users can create their own user accounts by clicking the +``New Account`` link at the bottom of each page (assuming +they aren't logged in as someone else already). If you want to disable +this self-registration, or if you want to restrict who can create their +own user account, you have to edit the :param:`createemailregexp` +parameter in the ``Configuration`` page; see +:ref:`parameters`. + +.. _user-account-creation: + +Administrator Registration +-------------------------- + +Users with ``editusers`` privileges, such as administrators, +can create user accounts for other users: + +#. After logging in, click the "Users" link at the footer of + the query page, and then click "Add a new user". + +#. Fill out the form presented. This page is self-explanatory. + When done, click "Submit". + + .. note:: Adding a user this way will *not* + send an email informing them of their username and password. + While useful for creating dummy accounts (watchers which + shuttle mail to another system, for instance, or email + addresses which are a mailing list), in general it is + preferable to log out and use the ``New Account`` + button to create users, as it will pre-populate all the + required fields and also notify the user of her account name + and password. + +.. _user-account-deletion: + +Deleting Users +============== + +If the :param:`allowuserdeletion` parameter is turned on (see +:ref:`parameters`) then you can also delete user accounts. +Note that, most of the time, this is not the best thing to do. If only +a warning in a yellow box is displayed, then the deletion is safe. +If a warning is also displayed in a red box, then you should NOT try +to delete the user account, else you will get referential integrity +problems in your database, which can lead to unexpected behavior, +such as bugs not appearing in bug lists anymore, or data displaying +incorrectly. You have been warned! + +.. _impersonatingusers: + +Impersonating Users +=================== + +There may be times when an administrator would like to do something as +another user. The :command:`sudo` feature may be used to do +this. + +.. note:: To use the sudo feature, you must be in the + *bz_sudoers* group. By default, all + administrators are in this group. + +If you have access to this feature, you may start a session by +going to the Edit Users page, Searching for a user and clicking on +their login. You should see a link below their login name titled +"Impersonate this user". Click on the link. This will take you +to a page where you will see a description of the feature and +instructions for using it. After reading the text, simply +enter the login of the user you would like to impersonate, provide +a short message explaining why you are doing this, and press the +button. + +As long as you are using this feature, everything you do will be done +as if you were logged in as the user you are impersonating. + +.. warning:: The user you are impersonating will not be told about what you are + doing. If you do anything that results in mail being sent, that + mail will appear to be from the user you are impersonating. You + should be extremely careful while using this feature. + diff --git a/docs/en/rst/administering/whining.rst b/docs/en/rst/administering/whining.rst new file mode 100644 index 000000000..dc101ab9b --- /dev/null +++ b/docs/en/rst/administering/whining.rst @@ -0,0 +1,145 @@ +.. _whining: + +Whining +####### + +Whining is a feature in Bugzilla that can regularly annoy users at +specified times. Using this feature, users can execute saved searches +at specific times (e.g. the 15th of the month at midnight) or at +regular intervals (e.g. every 15 minutes on Sundays). The results of the +searches are sent to the user, either as a single email or as one email +per bug, along with some descriptive text. + +.. warning:: Throughout this section it will be assumed that all users are members + of the bz_canusewhines group, membership in which is required in order + to use the Whining system. You can easily make all users members of + the bz_canusewhines group by setting the User RegExp to ".*" (without + the quotes). + + Also worth noting is the bz_canusewhineatothers group. Members of this + group can create whines for any user or group in Bugzilla using an + extended form of the whining interface. Features only available to + members of the bz_canusewhineatothers group will be noted in the + appropriate places. + +.. note:: For whining to work, a special Perl script must be executed at regular + intervals. More information on this is available in :ref:`installation-whining`. + +.. note:: This section does not cover the whineatnews.pl script. + See :ref:`installation-whining-cron` for more information on + The Whining Cron. + +.. _whining-overview: + +The Event +========= + +The whining system defines an "Event" as one or more queries being +executed at regular intervals, with the results of said queries (if +there are any) being emailed to the user. Events are created by +clicking on the "Add new event" button. + +Once a new event is created, the first thing to set is the "Email +subject line". The contents of this field will be used in the subject +line of every email generated by this event. In addition to setting a +subject, space is provided to enter some descriptive text that will be +included at the top of each message (to help you in understanding why +you received the email in the first place). + +The next step is to specify when the Event is to be run (the Schedule) +and what searches are to be performed (the Searches). + +.. _whining-schedule: + +Whining Schedule +================ + +Each whining event is associated with zero or more schedules. A +schedule is used to specify when the search (specified below) is to be +run. A new event starts out with no schedules (which means it will +never run, as it is not scheduled to run). To add a schedule, press +the "Add a new schedule" button. + +Each schedule includes an interval, which you use to tell Bugzilla +when the event should be run. An event can be run on certain days of +the week, certain days of the month, during weekdays (defined as +Monday through Friday), or every day. + +.. warning:: Be careful if you set your event to run on the 29th, 30th, or 31st of + the month, as your event may not run exactly when expected. If you + want your event to run on the last day of the month, select "Last day + of the month" as the interval. + +Once you have specified the day(s) on which the event is to be run, you +should now specify the time at which the event is to be run. You can +have the event run at a certain hour on the specified day(s), or +every hour, half-hour, or quarter-hour on the specified day(s). + +If a single schedule does not execute an event as many times as you +would want, you can create another schedule for the same event. For +example, if you want to run an event on days whose numbers are +divisible by seven, you would need to add four schedules to the event, +setting the schedules to run on the 7th, 14th, 21st, and 28th (one day +per schedule) at whatever time (or times) you choose. + +.. note:: If you are a member of the bz_canusewhineatothers group, then you + will be presented with another option: "Mail to". Using this you + can control who will receive the emails generated by this event. You + can choose to send the emails to a single user (identified by email + address) or a single group (identified by group name). To send to + multiple users or groups, create a new schedule for each additional + user/group. + +.. _whining-query: + +Whining Searches +================ + +Each whining event is associated with zero or more searches. A search +is any saved search to be run as part of the specified schedule (see +above). You start out without any searches associated with the event +(which means that the event will not run, as there will never be any +results to return). To add a search, press the "Add a search" button. + +The first field to examine in your newly added search is the Sort field. +Searches are run, and results included, in the order specified by the +Sort field. Searches with smaller Sort values will run before searches +with bigger Sort values. + +The next field to examine is the Search field. This is where you +choose the actual search that is to be run. Instead of defining search +parameters here, you are asked to choose from the list of saved +searches (the same list that appears at the bottom of every Bugzilla +page). You are only allowed to choose from searches that you have +saved yourself (the default saved search, "My Bugs", is not a valid +choice). If you do not have any saved searches, you can take this +opportunity to create one (see :ref:`list`). + +.. note:: When running searches, the whining system acts as if you are the user + executing the search. This means that the whining system will ignore + bugs that match your search but that you cannot access. + +Once you have chosen the saved search to be executed, give the search a +descriptive title. This title will appear in the email, above the +results of the search. If you choose "One message per bug", the search +title will appear at the top of each email that contains a bug matching +your search. + +Finally, decide if the results of the search should be sent in a single +email, or if each bug should appear in its own email. + +.. warning:: Think carefully before checking the "One message per bug" box. If + you create a search that matches thousands of bugs, you will receive + thousands of emails! + +Saving Your Changes +=================== + +Once you have defined at least one schedule and created at least one +search, go ahead and "Update/Commit". This will save your Event and make +it available for immediate execution. + +.. note:: If you ever feel like deleting your event, you may do so using the + "Remove Event" button in the upper-right corner of each Event. You + can also modify an existing event, so long as you "Update/Commit" + after completing your modifications. diff --git a/docs/en/rst/administering/workflow.rst b/docs/en/rst/administering/workflow.rst new file mode 100644 index 000000000..7ce5b7a87 --- /dev/null +++ b/docs/en/rst/administering/workflow.rst @@ -0,0 +1,34 @@ +.. _workflow: + +Workflow +######## + +The bug status workflow—which statuses are valid transitions from which +other statuses—can be customized. + +You need to begin by defining the statuses and resolutions you want to use +(see :ref:`field-values`). By convention, these are in all capital letters. + +Only one bug status, UNCONFIRMED, can never be renamed nor deleted. However, +it can be disabled entirely on a per-product basis (see :ref:`categorization`). +The status referred to by the :param:`duplicate_or_move_bug_status` parameter, if +set, is also undeletable. To make it deletable, +simply set the value of that parameter to a different status. + +Aside from the empty value, two resolutions, DUPLICATE and FIXED, cannot be +renamed or deleted. (FIXED could be if we fixed +`bug 1007605 `_.) + +Once you have defined your statuses, you can configure the workflow of +how a bug moves between them. The workflow configuration +page displays all existing bug statuses twice: first on the left for the +starting status, and on the top for the target status in the transition. +If the checkbox is checked, then the transition from the left to the top +status is legal; if it's unchecked, that transition is forbidden. + +The status used as the :param:`duplicate_or_move_bug_status` parameter +(normally RESOLVED or its equivalent) is required to be a legal transition +from every other bug status, and so this is enforced on the page. + +The "View Comments Required on Status Transitions" link below the table +lets you set which transitions require a comment from the user. -- cgit v1.2.3-24-g4f1b