281809 - 'Groups' docs need improving

Status: RESOLVED FIXED

(Bugzilla :: Documentation, defect)

Description

[Shane H. W. Travis]

Some of the most common questions people have -- even developers who are 
otherwise familiar with the code -- seem to be about groups. The documentation 
is there, but it doesn't cover all the bases... and besides that, it's a *big* 
subject that could use all the coverage it can get.

Some common questions seem to be:
- Are groups and products one-to-one relationship? (They were in 2.16, but from 
2.18 forward they don't have to be. 2.18 changed groups to a sort of container 
that can hold as many products as you'd like.)
- Can I set things up so people who aren't in a group, and who aren't either 
the reporter or a cc: member, can still *read* bugs even if they can't edit 
them? (No, not at present. You can accomplish it by hacking Bugs::can_see_bugs 
to always return true, but this has other implications for security and access 
as well.)
- How do I completely conceal the existence of a product from non-group-members?
(attainable through entry+canedit, but an example would be good.)

I know I've heard more questions being asked on the subject as well. If anyone 
has any they've run across, add them here. (Answers would be good too. :)

Comment 1

[Shane H. W. Travis]

*** Bug 286040 has been marked as a duplicate of this bug. ***

Comment 2

[Marc Schumann [:Wurblzap]]

*** Bug 286040 has been marked as a duplicate of this bug. ***

Comment 3

[Joel Peshkin]

I agree... contributions to the docs are certainly welcome.

(In reply to comment #0)
> 
> Some common questions seem to be:
> - Are groups and products one-to-one relationship? (They were in 2.16, but from 
> 2.18 forward they don't have to be. 2.18 changed groups to a sort of container 
> that can hold as many products as you'd like.)

The do not have to be.

> - Can I set things up so people who aren't in a group, and who aren't either 
> the reporter or a cc: member, can still *read* bugs even if they can't edit 
> them? (No, not at present. You can accomplish it by hacking Bugs::can_see_bugs 
> to always return true, but this has other implications for security and access 
> as well.)

You can have a group that the bug is not in, but still has the CANEDIT
restriction.  That means that a user who is not in the group cannot edit it.

> - How do I completely conceal the existence of a product from non-group-members?
> (attainable through entry+canedit, but an example would be good.)
> 
Use ENTRY, MANDATORY/MANDATORY 

Comment 4

[Kevin Benton]

Attachment: How to make a product Read-Only

Just a stab at this.  Feel free to modify as necessary.  While it's true that the template documents CANEDIT, having it availble in the docs would be very helpful.

Comment 5

[Kevin Benton]

Comment on attachment 239078 [details] [diff] [review]
How to make a product Read-Only

Replacing with updated version.  r-'ing my own attachment.

Comment 6

[Kevin Benton]

Attachment: New & Improved

Comment 7

[Kevin Benton]

Anyone able to review this attachment?

Comment 8

[Kevin Benton]

Comment on attachment 258423 [details] [diff] [review]
New & Improved

Thanks for the comments LpSolit.  Note to self:  I need to update this so that inherit is discussed here.

Comment 9

[Kevin Benton]

Attachment: How to make a product read-only

Rather than worrying about inherit now, let's get this patch in since it addresses making a product read-only and that's all.

Comment 10

[Frédéric Buclin]

Comment on attachment 287459 [details] [diff] [review]
How to make a product read-only

We are far from what this section needs, see e.g. comment 8. Moreover, the doc should include a section about what happens when you try to delete a group used in products or which contains users.

Comment 11

[Sam Folk-Williams]

I took a stab at this section with a previous bug on group access controls. I have been thinking about other improvements to the section as a whole and I am working on those now.

Comment 12

[Sam Folk-Williams]

Attachment: draft1

This patch contains significant changes to both the groups section and the products section. It incorporates Kevin's read-only bits as well.

Comment 13

[Sam Folk-Williams]

Comment on attachment 302468 [details] [diff] [review]
draft1

lpsolit - requesting additional review from yourself as well (changes i think are significant)

Comment 15

[Frédéric Buclin]

Comment on attachment 302468 [details] [diff] [review]
draft1

Docs doesn't compile:

jade:../xml/administration.xml:1503:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1523:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1529:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1533:70:E: fin d'étiquette pour l'élément "emphais" lequel n'est pas ouvert
jade:../xml/administration.xml:1538:14:E: fin d'étiquette pour "emphasis" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1533:47: début d'étiquette était ici
jade:../xml/administration.xml:1539:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1547:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1553:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1558:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1563:13:E: type de document ne permet pas l'élément "para" ici; manque un de "footnote", "caution", "important", "note", "tip", "warning", "blockquote", "informalexample" de l'étiquette de début
jade:../xml/administration.xml:1572:42:E: type de document ne permet pas l'élément "section" ici
jade:../xml/administration.xml:1590:13:E: type de document ne permet pas l'élément "para" ici; assume "listitem" manquant de l'étiquette de début
jade:../xml/administration.xml:1621:22:E: fin d'étiquette pour "listitem" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1590:8: début d'étiquette était ici
jade:../xml/administration.xml:1627:18:E: type de document ne permet pas l'élément "para" ici; assume "listitem" manquant de l'étiquette de début
jade:../xml/administration.xml:1637:22:E: fin d'étiquette pour "listitem" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1627:13: début d'étiquette était ici
jade:../xml/administration.xml:1643:15:E: type de document ne permet pas l'élément "para" ici; assume "listitem" manquant de l'étiquette de début
jade:../xml/administration.xml:1653:22:E: fin d'étiquette pour "listitem" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1643:10: début d'étiquette était ici
jade:../xml/administration.xml:1660:15:E: type de document ne permet pas l'élément "para" ici; assume "listitem" manquant de l'étiquette de début
jade:../xml/administration.xml:1710:22:E: fin d'étiquette pour "listitem" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1660:10: début d'étiquette était ici
jade:../xml/administration.xml:1717:15:E: type de document ne permet pas l'élément "para" ici; assume "listitem" manquant de l'étiquette de début
jade:../xml/administration.xml:1729:22:E: fin d'étiquette pour "listitem" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1717:10: début d'étiquette était ici
jade:../xml/administration.xml:1742:11:E: fin d'étiquette pour "para" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1497:8: début d'étiquette était ici
jade:../xml/administration.xml:3269:9:E: fin d'étiquette pour "section" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:2615:2: début d'étiquette était ici
jade:../xml/administration.xml:3269:9:E: fin d'étiquette pour "section" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1448:4: début d'étiquette était ici
jade:../xml/administration.xml:3269:9:E: fin d'étiquette pour "section" omise mais OMITTAG NO était spécifié
jade:../xml/administration.xml:1253:2: début d'étiquette était ici

Comment 16

[Sam Folk-Williams]

Attachment: draft2

OK I figured out how to compile the docs :-) this would should work.

-Sam

Comment 17

[Frédéric Buclin]

Comment on attachment 302870 [details] [diff] [review]
draft2

>+      To edit an existing product, click the "Products" link from the 
>+      "Administration" page. A table of existing classifications is displayed,

Classifications are displayed only if the 'useclassification' parameter is turned on, else the list of all products is displayed.


>+        Bugzilla installation is displayed. The default groups that are created
>+        when Bugzilla is installed are not applicable to Group Access Controls.

Rather than "default groups", write "system groups". System groups include admin, canconfirm, editbugs, etc... privs.


>+             The group configuration page. To view or edit exiting groups, or to

s/exiting/existing/


>-           <note>
>-             <para>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.</para>
>-           </note>

Do not remove this note as it seems to be still useful to me. This note explains why this field is still here.


>+       The "Group Permissions" section on the "Edit Groups" page contains four
>+       sets of permissions that control the relationship of this group to other

The number of sets depends on the 'usevisibilitygroup' parameter. If turned off, then the four sets you mention are displayed. If turned on, two additional sets are displayed, which define which users you can see based on their membership to groups.


Your patch looks good, but please attach another one with my comments addressed.

Comment 18

[Sam Folk-Williams]

(In reply to comment #17)

> 
> 
> >-           <note>
> >-             <para>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.</para>
> >-           </note>
> 
> Do not remove this note as it seems to be still useful to me. This note
> explains why this field is still here.
> 

So what I did is move this into the paragraph above itself. I was thinking we don't need a separate note because 2.16 is so old at this point. I added this:
"Older versions of Bugzilla did not automatically
               remove users who's email addresses no longer matched the RegExp"

Is that sufficient or you prefer the note? All the other suggestions look great.

-Sam

Comment 19

[Sam Folk-Williams]

Attachment: draft2

comments addressed, except for the one from my last comment

Comment 20

[Sam Folk-Williams]

Attachment: draft3

fixed 2 nits from lpsolit on IRC...

Comment 21

[Frédéric Buclin]

Comment on attachment 303148 [details] [diff] [review]
draft3

Great job! r=LpSolit

Comment 22

[Frédéric Buclin]

The patch unfortunately doesn't apply cleanly to 3.0.

Comment 23

[Frédéric Buclin]

tip:

Checking in docs/xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  administration.xml
new revision: 1.86; previous revision: 1.85
done

Leaving the bug open till the backport for 3.0 is checked in.

Comment 24

[Frédéric Buclin]

Sam, keep in mind that the UI is different in 3.0 (compared to 3.2).

Comment 27

[Sam Folk-Williams]

Attachment: draft 1 of 3.0 backport

This compiles fine and I think I got all the changes from 3.2.

Comment 28

[Frédéric Buclin]

Comment on attachment 303880 [details] [diff] [review]
draft 1 of 3.0 backport

>+            There are five fields to fill out. These fields are documented below

In 3.0, there are only four fields as you cannot define an icon to use with the group.


>+       The "Edit Groups" page contains the same five fields present when 

Same here.

Both can be fixed on checkin. r=LpSolit

Comment 29

[Frédéric Buclin]

3.0.3:

Checking in xml/administration.xml;
/cvsroot/mozilla/webtools/bugzilla/docs/xml/administration.xml,v  <--  administration.xml
new revision: 1.70.2.12; previous revision: 1.70.2.11
done