From 91a1fcfa4fbc2dff0eee8bee2d7f20492176c4fe Mon Sep 17 00:00:00 2001 From: "gerv%gerv.net" <> Date: Fri, 4 Apr 2008 11:47:29 +0000 Subject: Bug 225687 - add group controls to charts, along with various other cleanups. Patch by gerv; r=joel, a=justdave. --- docs/en/xml/using.xml | 604 ++------------------------------------------------ 1 file changed, 24 insertions(+), 580 deletions(-) (limited to 'docs/en/xml/using.xml') diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml index d6c14dbd1..da7dc0363 100644 --- a/docs/en/xml/using.xml +++ b/docs/en/xml/using.xml @@ -261,28 +261,6 @@ -
- Life Cycle of a Bug - - - The life cycle, also known as work flow, of a bug is currently hardcoded - into Bugzilla. contains a graphical - repsentation of this life cycle. If you wish to customize this image for - your site, the diagram file - is available in Dia's - native XML format. - - -
- Lifecycle of a Bugzilla Bug - - - - - -
-
-
Searching for Bugs @@ -300,144 +278,8 @@ Once you've run a search, you can save it as a Saved Search, which appears in the page footer. -
- Boolean Charts - - Highly advanced querying is done using Boolean Charts. - - - The boolean charts further restrict the set of results - returned by a query. It is possible to search for bugs - based on elaborate combinations of critera. - - - The simplest boolean searches have only one term. These searches - permit the selected left field - to be compared using a - selectable operator to a - specified value. - Using the "And," "Or," and "Add Another Boolean Chart" buttons, - additonal terms can be included in the query, further - altering the list of bugs returned by the query. - - - There are three fields in each row of a boolean search. - - - - - Field: - the items being searched - - - - - Operator: - the comparison operator - - - - - Value: - the value to which the field is being compared - - - -
- Pronoun Substitution - - Sometimes, a query needs to compare a field containing - a user's ID (such as ReportedBy) with - a user's ID (such as the user running the query or the user - to whom each bug is assigned). When the operator is either - "equals" or "notequals", the value can be "%reporter%", - "%assignee%", "%qacontact%", or "%user%." The user pronoun - referes to the user who is executing the query or, in the case - of whining reports, the user who will be the recipient - of the report. The reporter, assignee, and qacontact - pronouns refer to the corresponding fields in the bug. - -
-
- Negation - - At first glance, negation seems redundant. Rather than - searching for -
- - NOT("summary" "contains the string" "foo"), - -
- one could search for -
- - ("summary" "does not contain the string" "foo"). - -
- However, the search -
- - ("CC" "does not contain the string" "@mozilla.org") - -
- would find every bug where anyone on the CC list did not contain - "@mozilla.org" while -
- - NOT("CC" "contains the string" "@mozilla.org") - -
- would find every bug where there was nobody on the CC list who - did contain the string. Similarly, the use of negation also permits - complex expressions to be built using terms OR'd together and then - negated. Negation permits queries such as -
- - NOT(("product" "equals" "update") OR - ("component" "equals" "Documentation")) - -
- to find bugs that are neither - in the update product or in the documentation component or -
- - NOT(("commenter" "equals" "%assignee%") OR - ("component" "equals" "Documentation")) - -
- to find non-documentation - bugs on which the assignee has never commented. - -
-
- Multiple Charts - - The terms within a single row of a boolean chart are all - constraints on a single piece of data. If you are looking for - a bug that has two different people cc'd on it, then you need - to use two boolean charts. A search for -
- - ("cc" "contains the string" "foo@") AND - ("cc" "contains the string" "@mozilla.org") - -
- would return only bugs with "foo@mozilla.org" on the cc list. - If you wanted bugs where there is someone on the cc list - containing "foo@" and someone else containing "@mozilla.org", - then you would need two boolean charts. -
- - First chart: ("cc" "contains the string" "foo@") - - - Second chart: ("cc" "contains the string" "@mozilla.org") - -
- The bugs listed will be only the bugs where ALL the charts are true. - -
-
+ Highly advanced querying is done using Boolean Charts. See the + Boolean Charts help link on the Search page for more information.
@@ -461,22 +303,7 @@ get the buglist as comma-separated values, for import into e.g. a spreadsheet. - - - RSS - - get the buglist as an RSS 1.0 feed. Copy this link into your - favorite feed reader. If you are using Firefox, you can also - save the list as a live bookmark by clicking the live bookmark - icon in the status bar. To limit the number of bugs in the feed, - add a limit=n parameter to the URL. - - - iCalendar - - Get the buglist as an iCalendar file. Each bug is represented as a - to-do item in the imported calendar. - + Change Columns: @@ -487,12 +314,12 @@ If your account is sufficiently empowered, you can make the same change to all the bugs in the list - for example, changing their - assignee. + owner. - Send mail to bug assignees: + Send mail to bug owners: - Sends mail to the assignees of all bugs on the list. + Sends mail to the owners of all bugs on the list. Edit Search: @@ -509,17 +336,6 @@ - - - If you would like to access the bug list from another program - it is often useful to have the list returned in something other - than HTML. By adding the ctype=type parameter into the bug list URL - you can specify several alternate formats. The supported formats - are: Comma Separated Values (ctype=csv), iCalendar (ctype=ics), - RDF Site Summary (RSS) 1.0 (ctype=rss), ECMAScript, also known - as JavaScript (ctype=js), and finally Resource Description Framework - RDF/XML (ctype=rdf). -
@@ -803,144 +619,30 @@
Email Settings - - This tab controls the amount of email Bugzilla sends you. + On this tab you can reduce or increase the amount of email sent + you from Bugzilla, opting in our out depending on your relationship to + the bug and the change that was made to it. - - - The first item on this page is marked Users to watch. - When you enter one or more comma-delineated user accounts (usually email - addresses) into the text entry box, you will receive a copy of all the - bugmail those users are sent (security settings permitting). - This powerful functionality enables seamless transitions as developers - change projects or users go on holiday. - - - - - The ability to watch other users may not be available in all - Bugzilla installations. If you don't see this feature, and feel - that you need it, speak to your administrator. - - - - - In general, users have almost complete control over how much (or - how little) email Bugzilla sends them. If you want to receive the - maximum amount of email possible, click the Enable All - Mail button. If you don't want to receive any email from - Bugzilla at all, click the Disable All Mail button. - - - - - Your Bugzilla administrator can stop a user from receiving - bugmail by adding the user's name to the - data/nomail file. This is a drastic step - best taken only for disabled accounts, as it overrides the - the user's individual mail preferences. - - - + - If you'd like to set your bugmail to something besides - 'Completely ON' and 'Completely OFF', the - Field/recipient specific options table - allows you to do just that. The rows of the table - define events that can happen to a bug -- things like - attachments being added, new comments being made, the - priority changing, etc. The columns in the table define - your relationship with the bug: - - - - - - Reporter - Where you are the person who initially - reported the bug. Your name/account appears in the - Reporter: field. - - - - - Assignee - Where you are the person who has been - designated as the one responsible for the bug. Your - name/account appears in the Assigned To: - field of the bug. - - - - - QA Contact - You are one of the designated - QA Contacts for the bug. Your account appears in the - QA Contact: text-box of the bug. - - - - - CC - You are on the list CC List for the bug. - Your account appears in the CC: text box - of the bug. - - - - - Voter - You have placed one or more votes for the bug. - Your account appears only if someone clicks on the - Show votes for this bug link on the bug. - - - - - - - - Some columns may not be visible for your installation, depending - on your site's configuration. - - + You can also do further filtering on the client side by + using the X-Bugzilla-Reason mail header which Bugzilla + adds to all bugmail. This tells you what relationship you have to the + bug in question, + and can be any of Owner, Reporter, QAcontact, CClist, Voter and + WatchingComponent. - - To fine-tune your bugmail, decide the events for which you want - to receive bugmail; then decide if you want to receive it all - the time (enable the checkbox for every column), or only when - you have a certain relationship with a bug (enable the checkbox - only for those columns). For example: if you didn't want to - receive mail when someone added themselves to the CC list, you - could uncheck all the boxes in the CC Field Changes - line. As another example, if you never wanted to receive email - on bugs you reported unless the bug was resolved, you would - un-check all boxes in the Reporter column - except for the one on the The bug is resolved or - verified row. - + By entering user email names, delineated by commas, into the + "Users to watch" text entry box you can receive a copy of all the + bugmail of other users (security settings permitting.) This powerful + functionality enables seamless transitions as developers change + projects or users go on holiday. - - Bugzilla adds the X-Bugzilla-Reason header to - all bugmail it sends, describing the recipient's relationship - (AssignedTo, Reporter, QAContact, CC, or Voter) to the bug. - This header can be used to do further client-side filtering. - + The ability to watch other users may not be available in all + Bugzilla installations. If you can't see it, ask your + administrator. - - - Two items not in the table (Email me when someone - asks me to set a flag and Email me when someone - sets a flag I asked for) define how you want to - receive bugmail with regards to flags. Their use is quite - straightforward; enable the checkboxes if you want Bugzilla to - send you mail under either of the above conditions. - - - - By default, Bugzilla sends out email regardless of who made the - change... even if you were the one responsible for generating - the email in the first place. If you don't care to receive bugmail - from your own changes, check the box marked Only email me - reports of changes made by other people. - -
@@ -1110,264 +812,6 @@
-
- Flags - - - A flag is a kind of status that can be set on bugs or attachments - to indicate that the bugs/attachments are in a certain state. - Each installation can define its own set of flags that can be set - on bugs or attachments. - - - - If your installation has defined a flag, you can set or unset that flag, - and if your administrator has enabled requesting of flags, you can submit - a request for another user to set the flag. - - - - To set a flag, select either "+" or "-" from the drop-down menu next to - the name of the flag in the "Flags" list. The meaning of these values are - flag-specific and thus cannot be described in this documentation, - but by way of example, setting a flag named "review" to "+" may indicate - that the bug/attachment has passed review, while setting it to "-" - may indicate that the bug/attachment has failed review. - - - - To unset a flag, click its drop-down menu and select the blank value. - - - - If your administrator has enabled requests for a flag, request a flag - by selecting "?" from the drop-down menu and then entering the username - of the user you want to set the flag in the text field next to the menu. - - - - A set flag appears in bug reports and on "edit attachment" pages with the - abbreviated username of the user who set the flag prepended to the - flag name. For example, if Jack sets a "review" flag to "+", it appears - as Jack: review [ + ] - - - - A requested flag appears with the user who requested the flag prepended - to the flag name and the user who has been requested to set the flag - appended to the flag name within parentheses. For example, if Jack - asks Jill for review, it appears as Jack: review [ ? ] (Jill). - -
- -
- 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 (i.e. the 15th of the month at midnight) or at - regular intervals (i.e. 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. - - - - - 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 a - extended form of the whining interface. Features only available to - members of the bz_canusewhineatothers group will be noted in the - appropriate places. - - - - - - For whining to work, a special Perl script must be executed at regular - intervals. More information on this is available in - . - - - - - - This section does not cover the whineatnews.pl script. See - for more information on - The Whining Cron. - - - -
- 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 Queries). - - -
- -
- Whining Schedule - - - Each whining event is associated with zero or more schedules. A - schedule is used to specify when the query (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. - - - - - 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. - - - - - 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 Queries - - - Each whining event is associated with zero or more queries. A query is - a saved search that is executed on the schedule specified (see above). - You start out with zero queries attached to the event (which means that - the event will not run, as there will never be any results to return). - To add a query, press the "Add a new query" button. - - - - The first field to examine in your new query is the Sort field. Queries - are executed, and results returned, in the order specified by the Sort - field. Queries with lower Sort values will run before queries with - higher 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 ). - - - - - When running queries, the whining system acts as if you are the user - executing the query. This means that the whining system will ignore - bugs that match your query, but that you can not access. - - - - - Once you have chosen the saved search to be executed, give the query a - descriptive title. This title will appear in the email, above the - results of the query. If you choose "One message per bug", the query - title will appear at the top of each email that contains a bug matching - your query. - - - - Finally, decide if the results of the query should be sent in a single - email, or if each bug should appear in its own email. - - - - - Think carefully before checking the "One message per bug" box. If - you create a query 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 - query, go ahead and "Update/Commit". This will save your Event and make - it available for immediate execution. - - - - - 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. - - -
- -
-