diff options
| -rw-r--r-- | docs/en/xml/installation.xml | 17 | ||||
| -rw-r--r-- | docs/en/xml/using.xml | 574 |
2 files changed, 563 insertions, 28 deletions
diff --git a/docs/en/xml/installation.xml b/docs/en/xml/installation.xml index 1b711ed39..65828412f 100644 --- a/docs/en/xml/installation.xml +++ b/docs/en/xml/installation.xml @@ -1,5 +1,5 @@ <!-- <!DOCTYPE chapter PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"> --> -<!-- $Id: installation.xml,v 1.99 2008/04/04 06:47:29 mozilla%colinogilvie.co.uk Exp $ --> +<!-- $Id: installation.xml,v 1.100 2008/04/04 06:47:30 mozilla%colinogilvie.co.uk Exp $ --> <chapter id="installing-bugzilla"> <title>Installing Bugzilla</title> @@ -651,6 +651,14 @@ 'max_allowed_packet' or 'maxattachmentsize' value will not be accepted by Bugzilla. </para> + + <note> + <para> + This does not affect Big Files, attachments that are stored directly + on disk instead of in the database. Their maximum size is + controlled using the 'maxlocalattachment' parameter. + </para> + </note> </section> @@ -707,6 +715,13 @@ to make a temporary copy of your entire table to do this. Ideally, you should do this when your attachments table is still small. </para> + + <note> + <para> + This does not affect Big Files, attachments that are stored directly + on disk instead of in the database. + </para> + </note> </section> <section id="install-setupdatabase-adduser"> diff --git a/docs/en/xml/using.xml b/docs/en/xml/using.xml index 8f616597a..720f461e9 100644 --- a/docs/en/xml/using.xml +++ b/docs/en/xml/using.xml @@ -234,8 +234,12 @@ <listitem> <para> <emphasis>Attachments:</emphasis> - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section.</para> + You can attach files (e.g. testcases or patches) to bugs. If there + are any attachments, they are listed in this section. Attachments are + normally stored in the Bugzilla database, unless they are marked as + Big Files, which are stored directly on disk and (unlike attachments + kept in the database) may be deleted at some future time. + </para> </listitem> <listitem> @@ -261,6 +265,28 @@ </orderedlist> </section> + <section id="lifecycle"> + <title>Life Cycle of a Bug</title> + + <para> + The life cycle, also known as work flow, of a bug is currently hardcoded + into Bugzilla. <xref linkend="lifecycle-image"/> contains a graphical + repsentation of this life cycle. If you wish to customize this image for + your site, the <ulink url="../images/bzLifecycle.xml">diagram file</ulink> + is available in <ulink url="http://www.gnome.org/projects/dia">Dia's</ulink> + native XML format. + </para> + + <figure id="lifecycle-image"> + <title>Lifecycle of a Bugzilla Bug</title> + <mediaobject> + <imageobject> + <imagedata fileref="../images/bzLifecycle.png" scale="66" /> + </imageobject> + </mediaobject> + </figure> + </section> + <section id="query"> <title>Searching for Bugs</title> @@ -278,8 +304,144 @@ <para>Once you've run a search, you can save it as a Saved Search, which appears in the page footer.</para> - <para>Highly advanced querying is done using Boolean Charts. See the - Boolean Charts help link on the Search page for more information.</para> + <section id="boolean"> + <title>Boolean Charts</title> + <para> + Highly advanced querying is done using Boolean Charts. + </para> + <para> + 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. + </para> + <para> + The simplest boolean searches have only one term. These searches + permit the selected left <emphasis>field</emphasis> + to be compared using a + selectable <emphasis>operator</emphasis> to a + specified <emphasis>value.</emphasis> + 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. + </para> + <para> + There are three fields in each row of a boolean search. + </para> + <itemizedlist> + <listitem> + <para> + <emphasis>Field:</emphasis> + the items being searched + </para> + </listitem> + <listitem> + <para> + <emphasis>Operator:</emphasis> + the comparison operator + </para> + </listitem> + <listitem> + <para> + <emphasis>Value:</emphasis> + the value to which the field is being compared + </para> + </listitem> + </itemizedlist> + <section id="pronouns"> + <title>Pronoun Substitution</title> + <para> + 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. + </para> + </section> + <section id="negation"> + <title>Negation</title> + <para> + At first glance, negation seems redundant. Rather than + searching for + <blockquote> + <para> + NOT("summary" "contains the string" "foo"), + </para> + </blockquote> + one could search for + <blockquote> + <para> + ("summary" "does not contain the string" "foo"). + </para> + </blockquote> + However, the search + <blockquote> + <para> + ("CC" "does not contain the string" "@mozilla.org") + </para> + </blockquote> + would find every bug where anyone on the CC list did not contain + "@mozilla.org" while + <blockquote> + <para> + NOT("CC" "contains the string" "@mozilla.org") + </para> + </blockquote> + 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 + <blockquote> + <para> + NOT(("product" "equals" "update") OR + ("component" "equals" "Documentation")) + </para> + </blockquote> + to find bugs that are neither + in the update product or in the documentation component or + <blockquote> + <para> + NOT(("commenter" "equals" "%assignee%") OR + ("component" "equals" "Documentation")) + </para> + </blockquote> + to find non-documentation + bugs on which the assignee has never commented. + </para> + </section> + <section id="multiplecharts"> + <title>Multiple Charts</title> + <para> + 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 + <blockquote> + <para> + ("cc" "contains the string" "foo@") AND + ("cc" "contains the string" "@mozilla.org") + </para> + </blockquote> + 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. + <blockquote> + <para> + First chart: ("cc" "contains the string" "foo@") + </para> + <para> + Second chart: ("cc" "contains the string" "@mozilla.org") + </para> + </blockquote> + The bugs listed will be only the bugs where ALL the charts are true. + </para> + </section> + </section> </section> <section id="list"> @@ -303,7 +465,22 @@ get the buglist as comma-separated values, for import into e.g. a spreadsheet.</member> - + + <member> + <emphasis>RSS</emphasis> + + 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.</member> + + <member> + <emphasis>iCalendar</emphasis> + + Get the buglist as an iCalendar file. Each bug is represented as a + to-do item in the imported calendar.</member> + <member> <emphasis>Change Columns:</emphasis> @@ -314,12 +491,12 @@ If your account is sufficiently empowered, you can make the same change to all the bugs in the list - for example, changing their - owner.</member> + assignee.</member> <member> - <emphasis>Send mail to bug owners:</emphasis> + <emphasis>Send mail to bug assignees:</emphasis> - Sends mail to the owners of all bugs on the list.</member> + Sends mail to the assignees of all bugs on the list.</member> <member> <emphasis>Edit Search:</emphasis> @@ -336,6 +513,17 @@ </member> </simplelist> </para> + + <para> + 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). + </para> </section> <section id="bugreports"> @@ -590,7 +778,17 @@ Content-Type (e.g. application/xhtml+xml), you can override this using a 'content-type' parameter on the URL, e.g. <filename>&content-type=text/plain</filename>. - </para> + </para> + + <para> + If you have a really large attachment, something that does not need to + be recorded forever (as most attachments are), you can mark your + attachment as a Big File, Assuming the administrator of the + installation has enabled this feature. Big Files are stored directly on + disk instead of in the database, and can be deleted when it is no longer + needed. The maximum size of a Big File is normally larger than the + maximum size of a regular attachment. + </para> </section> </section> @@ -619,30 +817,144 @@ <section id="emailsettings"> <title>Email Settings</title> - <para>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. + <para> + This tab controls the amount of email Bugzilla sends you. </para> - + <para> - 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.</para> + The first item on this page is marked <quote>Users to watch</quote>. + 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. + </para> - <para>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.</para> + <note> + <para> + 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. + </para> + </note> + + <para> + 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 <quote>Enable All + Mail</quote> button. If you don't want to receive any email from + Bugzilla at all, click the <quote>Disable All Mail</quote> button. + </para> <note> - <para>The ability to watch other users may not be available in all - Bugzilla installations. If you can't see it, ask your - administrator.</para> + <para> + Your Bugzilla administrator can stop a user from receiving + bugmail by adding the user's name to the + <filename>data/nomail</filename> file. This is a drastic step + best taken only for disabled accounts, as it overrides the + the user's individual mail preferences. + </para> </note> + + <para> + If you'd like to set your bugmail to something besides + 'Completely ON' and 'Completely OFF', the + <quote>Field/recipient specific options</quote> 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: + </para> + + <itemizedlist spacing="compact"> + <listitem> + <para> + Reporter - Where you are the person who initially + reported the bug. Your name/account appears in the + <quote>Reporter:</quote> field. + </para> + </listitem> + <listitem> + <para> + Assignee - Where you are the person who has been + designated as the one responsible for the bug. Your + name/account appears in the <quote>Assigned To:</quote> + field of the bug. + </para> + </listitem> + <listitem> + <para> + QA Contact - You are one of the designated + QA Contacts for the bug. Your account appears in the + <quote>QA Contact:</quote> text-box of the bug. + </para> + </listitem> + <listitem> + <para> + CC - You are on the list CC List for the bug. + Your account appears in the <quote>CC:</quote> text box + of the bug. + </para> + </listitem> + <listitem> + <para> + Voter - You have placed one or more votes for the bug. + Your account appears only if someone clicks on the + <quote>Show votes for this bug</quote> link on the bug. + </para> + </listitem> + </itemizedlist> + + + <note> + <para> + Some columns may not be visible for your installation, depending + on your site's configuration. + </para> + </note> + + <para> + 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 <quote>CC Field Changes</quote> + 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 <quote>Reporter</quote> column + except for the one on the <quote>The bug is resolved or + verified</quote> row. + </para> + + <note> + <para> + Bugzilla adds the <quote>X-Bugzilla-Reason</quote> 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. + </para> + </note> + + <para> + Two items not in the table (<quote>Email me when someone + asks me to set a flag</quote> and <quote>Email me when someone + sets a flag I asked for</quote>) 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. + </para> + + <para> + 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 <quote>Only email me + reports of changes made by other people</quote>. + </para> + </section> <section id="permissionsettings"> @@ -862,6 +1174,214 @@ </para> </section> + <section id="whining"> + <title>Whining</title> + + <para> + 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. + </para> + + <warning> + <para> + 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). + </para> + + <para> + 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. + </para> + </warning> + + <note> + <para> + For whining to work, a special Perl script must be executed at regular + intervals. More information on this is available in + <xref linkend="installation-whining"/>. + </para> + </note> + + <note> + <para> + This section does not cover the whineatnews.pl script. See + <xref linkend="installation-whining-cron"/> for more information on + The Whining Cron. + </para> + </note> + + <section id="whining-overview"> + <title>The Event</title> + + <para> + 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. + </para> + + <para> + 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). + </para> + + <para> + The next step is to specify when the Event is to be run (the Schedule) + and what searches are to be performed (the Queries). + </para> + + </section> + + <section id="whining-schedule"> + <title>Whining Schedule</title> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <warning> + <para> + 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. + </para> + </warning> + + <para> + 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). + </para> + + <para> + 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. + </para> + + <note> + <para> + 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. + </para> + </note> + </section> + + <section id="whining-query"> + <title>Whining Queries</title> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <para> + 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 <xref linkend="list"/>). + </para> + + <note> + <para> + 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. + </para> + </note> + + <para> + 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. + </para> + + <para> + 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. + </para> + + <warning> + <para> + 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! + </para> + </warning> + </section> + + <section> + <title>Saving Your Changes</title> + + <para> + 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. + </para> + + <note> + <para> + 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. + </para> + </note> + </section> + + </section> + </chapter> <!-- Keep this comment at the end of the file |