Bug 912064 - convert docs to ReStructured Text (.rst) format. r,a=justdave.

1 files changed, 1375 insertions, 0 deletions

diff --git a/docs/en/rst/using.rst b/docs/en/rst/using.rst
new file mode 100644
index 000000000..e5a16bfcb
--- /dev/null
+++ b/docs/en/rst/using.rst
@@ -0,0 +1,1375 @@
+
+
+.. _using:
+
+==============
+Using Bugzilla
+==============
+
+.. _using-intro:
+
+Introduction
+############
+
+This section contains information for end-users of Bugzilla.  There
+is a Bugzilla test installation, 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 this URL:
+`<|landfillbase|>`_.
+
+#. 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 <|landfillbase|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 here:
+`<|landfillbase|query.cgi>`_.
+
+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
+`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 <|landfillbase|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
+      `the Landfill server <|landfillbase|>`_.
+
+#. 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
+lack of context, improper format and the inherent readability issues that
+raw patches present.  Patch Viewer is an enhancement to Bugzilla designed
+to fix that by offering increased context, linking to sections, and
+integrating with Bonsai, LXR and CVS.
+
+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.
+
++ Get more context in a patch.
+
++ Collapse and expand sections of a patch for easy
+  reading.
+
++ Link to a particular section of a patch for discussion or
+  review
+
++ Go to Bonsai or LXR to see more context, blame, and
+  cross-references for the part of the patch you are looking at
+
++ 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_context:
+
+Getting More Context in a Patch
+-------------------------------
+
+To get more context in a patch, you put a number in the textbox at
+the top of Patch Viewer ("Patch / File / \[textbox]") and hit enter.
+This will give you that many lines of context before and after each
+change. Alternatively, you can click on the "File" link there and it
+will show each change in the full context of the file. This feature only
+works against files that were diffed using "cvs diff".
+
+.. _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_bonsai_lxr:
+
+Going to Bonsai and LXR
+-----------------------
+
+To go to Bonsai to get blame for the lines you are interested in,
+you can click the "Lines XX-YY" link on the section header you are
+interested in. This works even if the patch is against an old
+version of the file, since Bonsai stores all versions of the file.
+
+To go to LXR, you click on the filename on the file header
+(unfortunately, since LXR only does the most recent version, line
+numbers are likely to rot).
+
+.. _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
+
++ comment 7
+
++ 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.
+
+.. _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.
+
+- Enable tags for bugs - turn bug tagging on or off.
+
+- 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:
+
+Name and Password
+=================
+
+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.
+
+.. _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.
+
+