diff options
Diffstat (limited to 'docs/en/rst/using.rst')
| -rw-r--r-- | docs/en/rst/using.rst | 1378 |
1 files changed, 0 insertions, 1378 deletions
diff --git a/docs/en/rst/using.rst b/docs/en/rst/using.rst deleted file mode 100644 index eb887093b..000000000 --- a/docs/en/rst/using.rst +++ /dev/null @@ -1,1378 +0,0 @@ - - -.. _using: - -============== -Using Bugzilla -============== - -.. _using-intro: - -Introduction -############ - -This section contains information for end-users of Bugzilla. There -is a machine with many Bugzilla test installations, called -`Landfill <http://landfill.bugzilla.org/>`_, which you are -welcome to play with (if it's up). However, not all of the Bugzilla -installations there will necessarily have all Bugzilla features enabled, -and different installations run different versions, so some things may not -quite work as this document describes. - -Frequently Asked Questions (FAQ) are available and answered on -`wiki.mozilla.org <http://wiki.mozilla.org/Bugzilla:FAQ>`_. -They may cover some questions you have which are left unanswered. - -.. _myaccount: - -Create a Bugzilla Account -######################### - -If you want to use Bugzilla, first you need to create an account. -Consult with the administrator responsible for your installation of -Bugzilla for the URL you should use to access it. If you're -test-driving Bugzilla, use an installation on -`Landfill <http://landfill.bugzilla.org/>`_. - -#. On the home page :file:`index.cgi`, click the - ``Open a new Bugzilla account`` link, or the - ``New Account`` link available in the footer of pages. - Now enter your email address, then click the ``Send`` - button. - - .. note:: If none of these links is available, this means that the - administrator of the installation has disabled self-registration. - This means that only an administrator can create accounts - for other users. One reason could be that this installation is - private. - - .. note:: Also, if only some users are allowed to create an account on - the installation, you may see these links but your registration - may fail if your email address doesn't match the ones accepted - by the installation. This is another way to restrict who can - access and edit bugs in this installation. - -#. Within moments, and if your registration is accepted, you should - receive an email to the address you provided, which contains your - login name (generally the same as the email address), and two URLs - with a token (a random string generated by the installation) to - confirm, respectively cancel, your registration. This is a way to - prevent users from abusing the generation of user accounts, for - instance by entering inexistent email addresses, or email addresses - which do not belong to them. - -#. By default, you have 3 days to confirm your registration. Past this - timeframe, the token is invalidated and the registration is - automatically canceled. You can also cancel this registration sooner - by using the appropriate URL in the email you got. - -#. If you confirm your registration, Bugzilla will ask you your real name - (optional, but recommended) and your password, which must be between - 3 and 16 characters long. - -#. Now all you need to do is to click the ``Log In`` - link in the footer at the bottom of the page in your browser, - enter your email address and password you just chose into the - login form, and click the ``Log in`` button. - -You are now logged in. Bugzilla uses cookies to remember you are -logged in so, unless you have cookies disabled or your IP address changes, -you should not have to log in again during your session. - -.. _bug_page: - -Anatomy of a Bug -################ - -The core of Bugzilla is the screen which displays a particular -bug. It's a good place to explain some Bugzilla concepts. -`Bug 1 on Landfill <http://landfill.bugzilla.org/bugzilla-tip/show_bug.cgi?id=1>`_ -is a good example. Note that the labels for most fields are hyperlinks; -clicking them will take you to context-sensitive help on that -particular field. Fields marked * may not be present on every -installation of Bugzilla. - -#. *Product and Component*: - Bugs are divided up by Product and Component, with a Product - having one or more Components in it. For example, - bugzilla.mozilla.org's "Bugzilla" Product is composed of several - Components: - - Administration: - Administration of a Bugzilla installation. - Bugzilla-General: - Anything that doesn't fit in the other components, or spans - multiple components. - Creating/Changing Bugs: - Creating, changing, and viewing bugs. - Documentation: - The Bugzilla documentation, including The Bugzilla Guide. - Email: - Anything to do with email sent by Bugzilla. - Installation: - The installation process of Bugzilla. - Query/Buglist: - Anything to do with searching for bugs and viewing the - buglists. - Reporting/Charting: - Getting reports from Bugzilla. - User Accounts: - Anything about managing a user account from the user's perspective. - Saved queries, creating accounts, changing passwords, logging in, - etc. - User Interface: - General issues having to do with the user interface cosmetics (not - functionality) including cosmetic issues, HTML templates, - etc. - -#. *Status and Resolution:* - These define exactly what state the bug is in - from not even - being confirmed as a bug, through to being fixed and the fix - confirmed by Quality Assurance. The different possible values for - Status and Resolution on your installation should be documented in the - context-sensitive help for those items. - -#. *Assigned To:* - The person responsible for fixing the bug. - -#. *\*QA Contact:* - The person responsible for quality assurance on this bug. - -#. *\*URL:* - A URL associated with the bug, if any. - -#. *Summary:* - A one-sentence summary of the problem. - -#. *\*Status Whiteboard:* - (a.k.a. Whiteboard) A free-form text area for adding short notes - and tags to a bug. - -#. *\*Keywords:* - The administrator can define keywords which you can use to tag and - categorise bugs - e.g. The Mozilla Project has keywords like crash - and regression. - -#. *Platform and OS:* - These indicate the computing environment where the bug was - found. - -#. *Version:* - The "Version" field is usually used for versions of a product which - have been released, and is set to indicate which versions of a - Component have the particular problem the bug report is - about. - -#. *Priority:* - The bug assignee uses this field to prioritize his or her bugs. - It's a good idea not to change this on other people's bugs. - -#. *Severity:* - This indicates how severe the problem is - from blocker - ("application unusable") to trivial ("minor cosmetic issue"). You - can also use this field to indicate whether a bug is an enhancement - request. - -#. *\*Target:* - (a.k.a. Target Milestone) A future version by which the bug is to - be fixed. e.g. The Bugzilla Project's milestones for future - Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not - restricted to numbers, thought - you can use any text strings, such - as dates. - -#. *Reporter:* - The person who filed the bug. - -#. *CC list:* - A list of people who get mail when the bug changes. - -#. *\*Time Tracking:* - This form can be used for time tracking. - To use this feature, you have to be blessed group membership - specified by the ``timetrackinggroup`` parameter. - - Orig. Est.: - This field shows the original estimated time. - Current Est.: - This field shows the current estimated time. - This number is calculated from ``Hours Worked`` - and ``Hours Left``. - Hours Worked: - This field shows the number of hours worked. - Hours Left: - This field shows the ``Current Est.`` - - ``Hours Worked``. - This value + ``Hours Worked`` will become the - new Current Est. - %Complete: - This field shows what percentage of the task is complete. - Gain: - This field shows the number of hours that the bug is ahead of the - ``Orig. Est.``. - Deadline: - This field shows the deadline for this bug. - -#. *Attachments:* - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section. - -#. *\*Dependencies:* - If this bug cannot be fixed unless other bugs are fixed (depends - on), or this bug stops other bugs being fixed (blocks), their - numbers are recorded here. - -#. *\*Votes:* - Whether this bug has any votes. - -#. *Additional Comments:* - You can add your two cents to the bug discussion here, if you have - something worthwhile to say. - -.. _lifecycle: - -Life Cycle of a Bug -################### - -The life cycle of a bug, also known as workflow, is customizable to match -the needs of your organization, see :ref:`bug_status_workflow`. -:ref:`lifecycle-image` contains a graphical representation of -the default workflow using the default bug statuses. If you wish to -customize this image for your site, the -`diagram file <../images/bzLifecycle.xml>`_ -is available in `Dia's <http://www.gnome.org/projects/dia>`_ -native XML format. - -.. _lifecycle-image: - -Lifecycle of a Bugzilla Bug -=========================== - -.. image:: ../images/bzLifecycle.png - -.. _query: - -Searching for Bugs -################## - -The Bugzilla Search page is the interface where you can find -any bug report, comment, or patch currently in the Bugzilla system. -`You can play with it on -Landfill <http://landfill.bugzilla.org/bugzilla-tip/query.cgi?format=advanced>`_. - -The Search page has controls for selecting different possible -values for all of the fields in a bug, as described above. For some -fields, multiple values can be selected. In those cases, Bugzilla -returns bugs where the content of the field matches any one of the selected -values. If none is selected, then the field can take any value. - -After a search is run, you can save it as a Saved Search, which -will appear in the page footer. If you are in the group defined -by the "querysharegroup" parameter, you may share your queries -with other users, see :ref:`savedsearches` for more details. - -.. _boolean: - -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 criteria. - -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, -additional 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 - -.. _pronouns: - -Pronoun Substitution --------------------- - -Sometimes, a query needs to compare a user-related field -(such as ReportedBy) with a role-specific user (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 -refers 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. - -Boolean charts also let you type a group name in any user-related -field if the operator is either "equals", "notequals" or "anyexact". -This will let you query for any member belonging (or not) to the -specified group. The group name must be entered following the -"%group.foo%" syntax, where "foo" is the group name. -So if you are looking for bugs reported by any user being in the -"editbugs" group, then you can type "%group.editbugs%". - -.. _negation: - -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. - -.. _multiplecharts: - -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. - -.. _quicksearch: - -Quicksearch -=========== - -Quicksearch is a single-text-box query tool which uses -metacharacters to indicate what is to be searched. For example, typing -"``foo|bar``" -into Quicksearch would search for "foo" or "bar" in the -summary and status whiteboard of a bug; adding -"``:BazProduct``" would -search only in that product. -You can use it to find a bug by its number or its alias, too. - -You'll find the Quicksearch box in Bugzilla's footer area. -On Bugzilla's front page, there is an additional -`quicksearcgh help <../../../page.cgi?id=quicksearch.html>`_ -link which details how to use it. - -.. _casesensitivity: - -Case Sensitivity in Searches -============================ - -Bugzilla queries are case-insensitive and accent-insensitive, when -used with either MySQL or Oracle databases. When using Bugzilla with -PostgreSQL, however, some queries are case-sensitive. This is due to -the way PostgreSQL handles case and accent sensitivity. - -.. _list: - -Bug Lists -========= - -If you run a search, a list of matching bugs will be returned. - -The format of the list is configurable. For example, it can be -sorted by clicking the column headings. Other useful features can be -accessed using the links at the bottom of the list: - -Long Format: - this gives you a large page with a non-editable summary of the fields - of each bug. - -XML: - get the buglist in the XML format. - -CSV: - get the buglist as comma-separated values, for import into e.g. - a spreadsheet. - -Feed: - get the buglist as an Atom 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: - change the bug attributes which appear in the list. - -Change several bugs at once: - If your account is sufficiently empowered, and more than one bug - appear in the bug list, this link is displayed which lets you make - the same change to all the bugs in the list - for example, changing - their assignee. - -Send mail to bug assignees: - If more than one bug appear in the bug list and there are at least - two distinct bug assignees, this links is displayed which lets you - easily send a mail to the assignees of all bugs on the list. - -Edit Search: - If you didn't get exactly the results you were looking for, you can - return to the Query page through this link and make small revisions - to the query you just made so you get more accurate results. - -Remember Search As: - You can give a search a name and remember it; a link will appear - in your page footer giving you quick access to run it again later. - -.. _individual-buglists: - -Adding/removing tags to/from bugs -================================= - -You can add and remove tags from individual bugs, which let you find and -manage bugs more easily. Tags are per-user and so are only visible and editable -by the user who created them. You can then run queries using tags as a criteria, -either by using the Advanced Search form, or simply by typing "tag:my_tag_name" -in the QuickSearch box at the top (or bottom) of the page. Tags can also be -displayed in buglists. - -This feature is useful when you want to keep track of several bugs, but -for different reasons. Instead of adding yourself to the CC list of all -these bugs and mixing all these reasons, you can now store these bugs in -separate lists, e.g. ``Keep in mind``, ``Interesting bugs``, -or ``Triage``. One big advantage of this way to manage bugs -is that you can easily add or remove tags from bugs one by one. - -.. _bugreports: - -Filing Bugs -########### - -.. _fillingbugs: - -Reporting a New Bug -=================== - -Years of bug writing experience has been distilled for your -reading pleasure into the -`Bug Writing Guidelines <http://landfill.bugzilla.org/bugzilla-tip/page.cgi?id=bug-writing.html>`_. -While some of the advice is Mozilla-specific, the basic principles of -reporting Reproducible, Specific bugs, isolating the Product you are -using, the Version of the Product, the Component which failed, the -Hardware Platform, and Operating System you were using at the time of -the failure go a long way toward ensuring accurate, responsible fixes -for the bug that bit you. - -The procedure for filing a bug is as follows: - -#. Click the ``New`` link available in the footer - of pages, or the ``Enter a new bug report`` link - displayed on the home page of the Bugzilla installation. - - .. note:: If you want to file a test bug to see how Bugzilla works, - you can do it on one of our test installations on - `Landfill <http://landfill.bugzilla.org/>`_. - -#. You first have to select the product in which you found a bug. - -#. You now see a form where you can specify the component (part of - the product which is affected by the bug you discovered; if you have - no idea, just select ``General`` if such a component exists), - the version of the program you were using, the Operating System and - platform your program is running on and the severity of the bug (if the - bug you found crashes the program, it's probably a major or a critical - bug; if it's a typo somewhere, that's something pretty minor; if it's - something you would like to see implemented, then that's an enhancement). - -#. You now have to give a short but descriptive summary of the bug you found. - ``My program is crashing all the time`` is a very poor summary - and doesn't help developers at all. Try something more meaningful or - your bug will probably be ignored due to a lack of precision. - The next step is to give a very detailed list of steps to reproduce - the problem you encountered. Try to limit these steps to a minimum set - required to reproduce the problem. This will make the life of - developers easier, and the probability that they consider your bug in - a reasonable timeframe will be much higher. - - .. note:: Try to make sure that everything in the summary is also in the first - comment. Summaries are often updated and this will ensure your original - information is easily accessible. - -#. As you file the bug, you can also attach a document (testcase, patch, - or screenshot of the problem). - -#. Depending on the Bugzilla installation you are using and the product in - which you are filing the bug, you can also request developers to consider - your bug in different ways (such as requesting review for the patch you - just attached, requesting your bug to block the next release of the - product, and many other product specific requests). - -#. Now is a good time to read your bug report again. Remove all misspellings, - otherwise your bug may not be found by developers running queries for some - specific words, and so your bug would not get any attention. - Also make sure you didn't forget any important information developers - should know in order to reproduce the problem, and make sure your - description of the problem is explicit and clear enough. - When you think your bug report is ready to go, the last step is to - click the ``Commit`` button to add your report into the database. - -You do not need to put "any" or similar strings in the URL field. -If there is no specific URL associated with the bug, leave this -field blank. - -If you feel a bug you filed was incorrectly marked as a -DUPLICATE of another, please question it in your bug, not -the bug it was duped to. Feel free to CC the person who duped it -if they are not already CCed. - -.. _cloningbugs: - -Clone an Existing Bug -===================== - -Starting with version 2.20, Bugzilla has a feature that allows you -to clone an existing bug. The newly created bug will inherit -most settings from the old bug. This allows you to track more -easily similar concerns in a new bug. To use this, go to the bug -that you want to clone, then click the ``Clone This Bug`` -link on the bug page. This will take you to the ``Enter Bug`` -page that is filled with the values that the old bug has. -You can change those values and/or texts if needed. - -.. _attachments: - -Attachments -########### - -You should use attachments, rather than comments, for large chunks of ASCII -data, such as trace, debugging output files, or log files. That way, it -doesn't bloat the bug for everyone who wants to read it, and cause people to -receive fat, useless mails. - -You should make sure to trim screenshots. There's no need to show the -whole screen if you are pointing out a single-pixel problem. - -Bugzilla stores and uses a Content-Type for each attachment -(e.g. text/html). To download an attachment as a different -Content-Type (e.g. application/xhtml+xml), you can override this -using a 'content_type' parameter on the URL, e.g. -:file:`&content_type=text/plain`. - -Also, you can enter the URL pointing to the attachment instead of -uploading the attachment itself. For example, this is useful if you want to -point to an external application, a website or a very large file. Note that -there is no guarantee that the source file will always be available, nor -that its content will remain unchanged. - -Another way to attach data is to paste text directly in the text field, -and Bugzilla will convert it into an attachment. This is pretty useful -when you do copy and paste, and you don't want to put the text in a temporary -file first. - -.. _patchviewer: - -Patch Viewer -============ - -Viewing and reviewing patches in Bugzilla is often difficult due to improper -format and the inherent readability issues that raw patches present. Patch -Viewer is an enhancement to Bugzilla designed to fix that by offering linking -to sections. - -Patch viewer allows you to: - -+ View patches in color, with side-by-side view rather than trying - to interpret the contents of the patch. - -+ See the difference between two patches. - -+ Collapse and expand sections of a patch for easy - reading. - -+ Link to a particular section of a patch for discussion or - review - -+ Create a rawtext unified format diff out of any patch, no - matter what format it came from - -.. _patchviewer_view: - -Viewing Patches in Patch Viewer -------------------------------- - -The main way to view a patch in patch viewer is to click on the -"Diff" link next to a patch in the Attachments list on a bug. You may -also do this within the edit window by clicking the "View Attachment As -Diff" button in the Edit Attachment screen. - -.. _patchviewer_diff: - -Seeing the Difference Between Two Patches ------------------------------------------ - -To see the difference between two patches, you must first view the -newer patch in Patch Viewer. Then select the older patch from the -dropdown at the top of the page ("Differences between \[dropdown] and -this patch") and click the "Diff" button. This will show you what -is new or changed in the newer patch. - -.. _patchviewer_collapse: - -Collapsing and Expanding Sections of a Patch --------------------------------------------- - -To view only a certain set of files in a patch (for example, if a -patch is absolutely huge and you want to only review part of it at a -time), you can click the "(+)" and "(-)" links next to each file (to -expand it or collapse it). If you want to collapse all files or expand -all files, you can click the "Collapse All" and "Expand All" links at the -top of the page. - -.. _patchviewer_link: - -Linking to a Section of a Patch -------------------------------- - -To link to a section of a patch (for example, if you want to be -able to give someone a URL to show them which part you are talking -about) you simply click the "Link Here" link on the section header. The -resulting URL can be copied and used in discussion. - -.. _patchviewer_unified_diff: - -Creating a Unified Diff ------------------------ - -If the patch is not in a format that you like, you can turn it -into a unified diff format by clicking the "Raw Unified" link at the top -of the page. - -.. _hintsandtips: - -Hints and Tips -############## - -This section distills some Bugzilla tips and best practices -that have been developed. - -Autolinkification -================= - -Bugzilla comments are plain text - so typing <U> will -produce less-than, U, greater-than rather than underlined text. -However, Bugzilla will automatically make hyperlinks out of certain -sorts of text in comments. For example, the text -"http://www.bugzilla.org" will be turned into a link: -`<http://www.bugzilla.org>`_. -Other strings which get linkified in the obvious manner are: - -+ bug 12345 - -+ bugs 123, 456, 789 - -+ comment 7 - -+ comments 1, 2, 3, 4 - -+ bug 23456, comment 53 - -+ attachment 4321 - -+ mailto:george@example.com - -+ george@example.com - -+ ftp://ftp.mozilla.org - -+ Most other sorts of URL - -A corollary here is that if you type a bug number in a comment, -you should put the word "bug" before it, so it gets autolinkified -for the convenience of others. - -.. _commenting: - -Comments -======== - -If you are changing the fields on a bug, only comment if -either you have something pertinent to say, or Bugzilla requires it. -Otherwise, you may spam people unnecessarily with bug mail. -To take an example: a user can set up their account to filter out messages -where someone just adds themselves to the CC field of a bug -(which happens a lot.) If you come along, add yourself to the CC field, -and add a comment saying "Adding self to CC", then that person -gets a pointless piece of mail they would otherwise have avoided. - -Don't use sigs in comments. Signing your name ("Bill") is acceptable, -if you do it out of habit, but full mail/news-style -four line ASCII art creations are not. - -.. _markdown: - -Markdown --------- - -Markdown lets you write your comments in a structured plain-text format and -have your comments generated as HTML. For example, you may use Markdown for -making a part of your comment look italic or bold in the generated HTML. Bugzilla -supports most of the structures defined by `standard Markdown <http://daringfireball.net/projects/markdown/basics>`_. -but does NOT support inline images and inline HTML. For a complete reference on -supported Markdown structures, please see the `syntax help <../../../page.cgi?id=markdown.html>`_ -link next to the markdown checkbox for new comments. - -To use the Markdown feature, make sure that ``Enable Markdown support for comments`` is set to ``on`` -in your :ref:`userpreferences` and that you also check the ``Use Markdown for this comment`` option below -the comment box when you want to submit a new comment. - -.. _comment-wrapping: - -Server-Side Comment Wrapping -============================ - -Bugzilla stores comments unwrapped and wraps them at display time. This -ensures proper wrapping in all browsers. Lines beginning with the ">" -character are assumed to be quotes, and are not wrapped. - -.. _dependencytree: - -Dependency Tree -=============== - -On the ``Dependency tree`` page linked from each bug -page, you can see the dependency relationship from the bug as a -tree structure. - -You can change how much depth to show, and you can hide resolved bugs -from this page. You can also collaps/expand dependencies for -each bug on the tree view, using the \[-]/\[+] buttons that appear -before its summary. This option is not available for terminal -bugs in the tree (that don't have further dependencies). - -.. _timetracking: - -Time Tracking Information -######################### - -Users who belong to the group specified by the ``timetrackinggroup`` -parameter have access to time-related fields. Developers can see -deadlines and estimated times to fix bugs, and can provide time spent -on these bugs. Users who do not belong to this group can only see the deadline, -but not edit it. Other time-related fields remain invisible to them. - -At any time, a summary of the time spent by developers on bugs is -accessible either from bug lists when clicking the ``Time Summary`` -button or from individual bugs when clicking the ``Summarize time`` -link in the time tracking table. The :file:`summarize_time.cgi` -page lets you view this information either per developer or per bug, -and can be split on a month basis to have greater details on how time -is spent by developers. - -As soon as a bug is marked as RESOLVED, the remaining time expected -to fix the bug is set to zero. This lets QA people set it again for -their own usage, and it will be set to zero again when the bug will -be marked as CLOSED. - -.. _userpreferences: - -User Preferences -################ - -Once logged in, you can customize various aspects of -Bugzilla via the "Preferences" link in the page footer. -The preferences are split into five tabs: - -.. _generalpreferences: - -General Preferences -=================== - -This tab allows you to change several default settings of Bugzilla. - -- Bugzilla's general appearance (skin) - select which skin to use. - Bugzilla supports adding custom skins. - -- Quote the associated comment when you click on its reply link - sets - the behavior of the comment "Reply" link. Options include quoting the - full comment, just reference the comment number, or turn the link off. - -- Language used in email - select which language email will be sent in, - from the list of available languages. - -- After changing a bug - This controls what page is displayed after - changes to a bug are submitted. The options include to show the bug - just modified, to show the next bug in your list, or to do nothing. - -- Zoom textareas large when in use (requires JavaScript) - enable or - disable the automatic expanding of text areas when text is being - entered into them. - -- Field separator character for CSV files - - Select between a comma and semi-colon for exported CSV bug lists. - -- Automatically add me to the CC list of bugs I change - set default - behavior of CC list. Options include "Always", "Never", and "Only - if I have no role on them". - -- When viewing a bug, show comments in this order - - controls the order of comments. Options include "Oldest - to Newest", "Newest to Oldest" and "Newest to Oldest, but keep the - bug description at the top". - -- Show a quip at the top of each bug list - controls - whether a quip will be shown on the Bug list page. - -.. _emailpreferences: - -Email Preferences -================= - -This tab allows you to enable or disable email notification on -specific events. - -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. - -.. note:: A Bugzilla administrator can stop a user from receiving - bugmail by clicking the ``Bugmail Disabled`` checkbox - when editing the user account. This is a drastic step - best taken only for disabled accounts, as it overrides - the user's individual mail preferences. - -There are two global options -- ``Email me when someone -asks me to set a flag`` and ``Email me when someone -sets a flag I asked for``. These 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. - -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. - -.. note:: Some columns may not be visible for your installation, depending - on your site's configuration. - -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. - -.. note:: 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. - -Bugzilla has a feature called ``Users Watching``. -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. - -.. note:: 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. - -Each user listed in the ``Users watching you`` field -has you listed in their ``Users to watch`` list -and can get bugmail according to your relationship to the bug and -their ``Field/recipient specific options`` setting. - -.. _savedsearches: - -Saved Searches -============== - -On this tab you can view and run any Saved Searches that you have -created, and also any Saved Searches that other members of the group -defined in the "querysharegroup" parameter have shared. -Saved Searches can be added to the page footer from this screen. -If somebody is sharing a Search with a group she or he is allowed to -:ref:`assign users to <groups>`, the sharer may opt to have -the Search show up in the footer of the group's direct members by default. - -.. _accountpreferences: - -Account Information -=================== - -On this tab, you can change your basic account information, -including your password, email address and real name. For security -reasons, in order to change anything on this page you must type your -*current* password into the ``Password`` -field at the top of the page. -If you attempt to change your email address, a confirmation -email is sent to both the old and new addresses, with a link to use to -confirm the change. This helps to prevent account hijacking. - -.. _apikey: - -API Keys -======== - -API keys are used to authenticate WebService API calls. You can create more than -one API key if required. Each API key has an optional description which can help -you record what each key is used for. - -On this page, you can unrevoke, revoke and change the description of existing -API keys for your login. A revoked key means that it cannot be used. The -description for purely for your information, and is optional. - -You can also create a new API key by selecting the check box under the 'New -API key' section of the page. - -.. _permissionsettings: - -Permissions -=========== - -This is a purely informative page which outlines your current -permissions on this installation of Bugzilla. - -A complete list of permissions is below. Only users with -*editusers* privileges can change the permissions -of other users. - -admin - Indicates user is an Administrator. - -bz_canusewhineatothers - Indicates user can configure whine reports for other users. - -bz_canusewhines - Indicates user can configure whine reports for self. - -bz_quip_moderators - Indicates user can moderate quips. - -bz_sudoers - Indicates user can perform actions as other users. - -bz_sudo_protect - Indicates user cannot be impersonated by other users. - -canconfirm - Indicates user can confirm a bug or mark it a duplicate. - -creategroups - Indicates user can create and destroy groups. - -editbugs - Indicates user can edit all bug fields. - -editclassifications - Indicates user can create, destroy, and edit classifications. - -editcomponents - Indicates user can create, destroy, and edit components. - -editkeywords - Indicates user can create, destroy, and edit keywords. - -editusers - Indicates user can edit or disable users. - -tweakparams - Indicates user can change Parameters. - -.. note:: For more information on how permissions work in Bugzilla (i.e. who can - change what), see :ref:`cust-change-permissions`. - -.. _reporting: - -Reports and Charts -################## - -As well as the standard buglist, Bugzilla has two more ways of -viewing sets of bugs. These are the reports (which give different -views of the current state of the database) and charts (which plot -the changes in particular sets of bugs over time.) - -.. _reports: - -Reports -======= - -A report is a view of the current state of the bug database. - -You can run either an HTML-table-based report, or a graphical -line/pie/bar-chart-based one. The two have different pages to -define them, but are close cousins - once you've defined and -viewed a report, you can switch between any of the different -views of the data at will. - -Both report types are based on the idea of defining a set of bugs -using the standard search interface, and then choosing some -aspect of that set to plot on the horizontal and/or vertical axes. -You can also get a form of 3-dimensional report by choosing to have -multiple images or tables. - -So, for example, you could use the search form to choose "all -bugs in the WorldControl product", and then plot their severity -against their component to see which component had had the largest -number of bad bugs reported against it. - -Once you've defined your parameters and hit "Generate Report", -you can switch between HTML, CSV, Bar, Line and Pie. (Note: Pie -is only available if you didn't define a vertical axis, as pie -charts don't have one.) The other controls are fairly self-explanatory; -you can change the size of the image if you find text is overwriting -other text, or the bars are too thin to see. - -.. _charts: - -Charts -====== - -A chart is a view of the state of the bug database over time. - -Bugzilla currently has two charting systems - Old Charts and New -Charts. Old Charts have been part of Bugzilla for a long time; they -chart each status and resolution for each product, and that's all. -They are deprecated, and going away soon - we won't say any more -about them. -New Charts are the future - they allow you to chart anything you -can define as a search. - -.. note:: Both charting forms require the administrator to set up the - data-gathering script. If you can't see any charts, ask them whether - they have done so. - -An individual line on a chart is called a data set. -All data sets are organised into categories and subcategories. The -data sets that Bugzilla defines automatically use the Product name -as a Category and Component names as Subcategories, but there is no -need for you to follow that naming scheme with your own charts if -you don't want to. - -Data sets may be public or private. Everyone sees public data sets in -the list, but only their creator sees private data sets. Only -administrators can make data sets public. -No two data sets, even two private ones, can have the same set of -category, subcategory and name. So if you are creating private data -sets, one idea is to have the Category be your username. - -Creating Charts ---------------- - -You create a chart by selecting a number of data sets from the -list, and pressing Add To List for each. In the List Of Data Sets -To Plot, you can define the label that data set will have in the -chart's legend, and also ask Bugzilla to Sum a number of data sets -(e.g. you could Sum data sets representing RESOLVED, VERIFIED and -CLOSED in a particular product to get a data set representing all -the resolved bugs in that product.) - -If you've erroneously added a data set to the list, select it -using the checkbox and click Remove. Once you add more than one -data set, a "Grand Total" line -automatically appears at the bottom of the list. If you don't want -this, simply remove it as you would remove any other line. - -You may also choose to plot only over a certain date range, and -to cumulate the results - that is, to plot each one using the -previous one as a baseline, so the top line gives a sum of all -the data sets. It's easier to try than to explain :-) - -Once a data set is in the list, one can also perform certain -actions on it. For example, one can edit the -data set's parameters (name, frequency etc.) if it's one you -created or if you are an administrator. - -Once you are happy, click Chart This List to see the chart. - -.. _charts-new-series: - -Creating New Data Sets ----------------------- - -You may also create new data sets of your own. To do this, -click the "create a new data set" link on the Create Chart page. -This takes you to a search-like interface where you can define -the search that Bugzilla will plot. At the bottom of the page, -you choose the category, sub-category and name of your new -data set. - -If you have sufficient permissions, you can make the data set public, -and reduce the frequency of data collection to less than the default -seven days. - -.. _flags: - -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. -Note that marking an attachment as obsolete automatically cancels all -pending requests for the attachment. - -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). - -You can browse through open requests made of you and by you by selecting -'My Requests' from the footer. You can also look at open requests limited -by other requesters, requestees, products, components, and flag names from -this page. Note that you can use '-' for requestee to specify flags with -'no requestee' set. - -.. _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 (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. - -.. 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 a - 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. - - |