diff --git a/mozilla/webtools/bugzilla/docs/en/xml/administration.xml b/mozilla/webtools/bugzilla/docs/en/xml/administration.xml
index 4bd33358ca4..c47e8f46a4c 100644
--- a/mozilla/webtools/bugzilla/docs/en/xml/administration.xml
+++ b/mozilla/webtools/bugzilla/docs/en/xml/administration.xml
@@ -533,6 +533,22 @@
+
+
+ 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 .
+
+
+
+
querysharegroup
@@ -1400,9 +1416,13 @@
- When editing a product there is also a link to edit
- .
+ When editing a product there is also a link to edit Group Access Controls,
+ see .
+
+
+ Creating New Products
+
To create a new product:
@@ -1439,121 +1459,319 @@
-
-
- Assigning Group Controls to Products
-
- On the Product Edit
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.
-
-
- Groups may be applicable, default, and
- mandatory 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.
-
-
- 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. This is an
- additional restriction that further limits
- what can be edited by a user.
-
-
- 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 fields indicate which
- bugs will be placed in this group according
- to the following definitions.
-
-
- For each group, it is possible to specify if
- membership in that group is:
-
-
-
-
- Required for bug entry.
-
-
-
-
- Not applicable to this product(NA),
- a possible restriction for a member of the
- group to place on a bug in this product(Shown),
- a default restriction for a member of the
- group to place on a bug in this product(Default),
- or a mandatory restriction to be placed on bugs
- in this product(Mandatory).
-
-
-
-
- Not applicable by non-members to this product(NA),
- a possible restriction for a non-member of the
- group to place on a bug in this product(Shown),
- a default restriction for a non-member of the
- group to place on a bug in this product(Default),
- or a mandatory restriction to be placed on bugs
- in this product when entered by a non-member(Mandatory).
-
-
-
-
- Required in order to make any change
- to bugs in this product including comments.
-
-
-
- These controls are often described in this order, so a
- product that requires a user to be a member of group "foo"
- to enter a bug and then requires that the bug stay restricted
- to group "foo" at all times and that only members of group "foo"
- can edit the bug even if they otherwise could see the bug would
- have its controls summarized by...
-
-foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
-
-
+
+ Editing Products
+
+ To edit an existing product, click the "Products" link from the
+ "Administration" page. If the '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 'useclassification' parameter is not in use, the table
+ lists all products directly. The product table summarizes the information
+ about the product 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.
+
+
+
+
+
+ Adding or Editing Components, Versions and Target Milestones
+
+ To edit existing, or add new, 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 a 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 .
+
+
+ For more information on versions, see .
+
+
+ For more information on milestones, see .
+
+
+
+
+ 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 .
+
+
+
+ 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 (e.g bugs in this product can be associated
+ with this group) , default (e.g. bugs in this product are in this group
+ by default), and mandatory (e.g. 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
+ for examples of
+ product and group relationships.
+
+
+
+
+ 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.
+
+
+
+ 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". The
+ "Bar" product can only have bugs entered against it by users in the
+ group "Foo". Additionally, bugs filed against product "Bar" must stay
+ restricted to users to "Foo" at all times. Furthermore, only members
+ of group "Foo" can 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". A
+ more lenient way to configure product "Bar" and group "Foo" would be:
+
+
+
+Product Bar:
+foo: ENTRY, SHOWN/SHOWN, EDITCOMPONENTS, CANCONFIRM, EDITBUGS
+
+
+
+ The above indicates that for product "Bar", members of group "Foo" can
+ enter bugs. Any one with permission to edit a bug against product "Bar"
+ can put the bug
+ in group "Foo", even if they themselves are not in "Foo". Anyone in group
+ "Foo" can edit all aspects of the components of product "Bar", can confirm
+ bugs against product "Bar", and can edit all fields of any bug against
+ product "Bar".
+
+
+
+ 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
+
+
+
+
+ For more information on Groups outside of how they relate to products
+ see .
+
+
+
+
+
+
@@ -2431,28 +2649,70 @@ foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
Groups and Group Security
- Groups allow the administrator
- to isolate bugs or products that should only be seen by certain people.
- The association between products and groups is controlled from
- the product edit page under Edit Group Controls.
+
+ Groups allow for separating bugs into logical divisions.
+ Groups are typically used to
+ 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.
- If the makeproductgroups param is on, a new group will be automatically
- created for every new product. It is primarily available for backward
- compatibility with older sites.
+ 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 .
+
+
+
+
+
+
+ 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 .
+
+
+
+
+
+ Group access for users. See for
+ details on how users are assigned group access.
+
+
+
+
+
- Note that group permissions are such that you need to be a member
- of all the groups a bug is in, for whatever
- reason, to see that bug. Similarly, you must be a member
- of all of the entry groups for a product
- to add bugs to a product and you must be a member
- of all of the canedit groups for a product
- in order to make any change to bugs in that
- product.
-
-
+ 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 .
+
+
+
By default, bugs can also be seen by the Assignee, the Reporter, and
by everyone on the CC List, regardless of whether or not the bug would
@@ -2461,158 +2721,276 @@ foo: ENTRY, MANDATORY/MANDATORY, CANEDIT
section that starts with Users in the roles selected below...
and un-checking the box next to either 'Reporter' or 'CC List' (or both).
-
+
+
Creating Groups
- To create Groups:
+
+
+ To create a new group, follow the steps below:
+
+
- Select the groups
- link in the footer.
+
+ Select the Administration
link in the page footer,
+ and then select the Groups
link from the
+ Administration page.
+
- Take a moment to understand the instructions on the Edit
- Groups
screen, then select the Add Group
link.
+
+ 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.
+
- Fill out the Group
, Description
,
- and User RegExp
fields.
- User RegExp
allows you to automatically
- place all users who fulfill the Regular Expression into the new group.
- When you have finished, click Add
.
- 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.
-
- This is a change from 2.16 where the regular expression
- resulted in a user acquiring permanent membership in a group.
- To remove a user from a group the user was in due to a regular
- expression in version 2.16 or earlier, the user must be explicitly
- removed from the group. This can easily be done by pressing
- buttons named 'Remove Memberships' or 'Remove Memberships
- included in regular expression' under the table.
-
-
- If specifying a domain in the regexp, make sure you end
- the regexp with a $. Otherwise, when granting access to
- "@mycompany\.com", you will allow access to
- 'badperson@mycompany.com.cracker.net'. You need to use
- '@mycompany\.com$' as the regexp.
-
+
+ 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).
+
+
+
+ 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 who's email addresses no longer matched the RegExp.
+
+
+
+
+ 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.
+
+
+
- If you plan to use this group to directly control
- access to bugs, check the "use for bugs" box. Groups
- not used for bugs are still useful because other groups
- can include the group as a whole.
-
-
- After you add your new group, edit the new group. On the
- edit page, you can specify other groups that should be included
+
+ 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.
+ users from this group. For more details, see .
+
+
- Assigning Users to Groups
- Users can become a member of a group in several ways.
-
-
- The user can be explicitly placed in the group by editing
- the user's own profile
-
-
- The group can include another group of which the user is
- a member.
-
-
- The user's email address can match a regular expression
- that the group specifies to automatically grant membership to
- the group.
-
-
+ 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 'usevisibilitygroups' parameter is in use (see
+ ) 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 'usevisibilitygroups' parameter
+ is enabled on the Bugzilla Configuration page. See
+ 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 'usevisibilitygroups' parameter
+ is enabled on the the Bugzilla Configuration page. See
+ for information on configuring Bugzilla.
+
+
+
+
+
+
+
+
+
+ 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 .
+
+
+
+
+
+ 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 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 for details on
+ the regular expression option when creating groups.
+
+
+
+
+
+
+
Assigning Group Controls to Products
+
- For information on assigning group controls to
- products, see .
+ 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 .
+
-
-
- Common Applications of Group Controls
-
- General User Access With Security Group
- To permit any user to file bugs in each product (A, B, C...)
- and to permit any user to submit those bugs into a security
- group....
-
-Product A...
-security: SHOWN/SHOWN
-Product B...
-security: SHOWN/SHOWN
-Product C...
-security: SHOWN/SHOWN
-
-
-
- General User Access With A Security Product
- To permit any user to file bugs in a Security product
- while keeping those bugs from becoming visible to anyone
- outside the securityworkers group unless a member of the
- securityworkers group removes that restriction....
-
-Product Security...
-securityworkers: DEFAULT/MANDATORY
-
-
-
- Product Isolation With Common Group
- To permit users of product A to access the bugs for
- product A, users of product B to access product B, and support
- staff to access both, 3 groups are needed
-
-
- Support: Contains members of the support staff.
-
-
- AccessA: Contains users of product A and the Support group.
-
-
- AccessB: Contains users of product B and the Support group.
-
-
- Once these 3 groups are defined, the products group controls
- can be set to..
-
-Product A...
-AccessA: ENTRY, MANDATORY/MANDATORY
-Product B...
-AccessB: ENTRY, MANDATORY/MANDATORY
-
- Optionally, the support group could be permitted to make
- bugs inaccessible to the users and could be permitted to publish
- bugs relevant to all users in a common product that is read-only
- to anyone outside the support group. That configuration could
- 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
-
-
-
+
@@ -2996,6 +3374,7 @@ bash$ ./checksetup.pl
+