Bug 1067416 - reorganize and update Bugzilla docs

9 files changed, 1212 insertions, 0 deletions

diff --git a/docs/en/rst/using/creating-an-account.rst b/docs/en/rst/using/creating-an-account.rst
new file mode 100644
index 000000000..0ea42ee5d
--- /dev/null
+++ b/docs/en/rst/using/creating-an-account.rst
@@ -0,0 +1,39 @@
+.. _creating-an-account:
+
+Creating an Account
+###################
+
+If you want to use a particular installation of Bugzilla, first you need to
+create an account. Ask the administrator responsible for your installation
+for the URL you should use to access it. If you're test-driving Bugzilla,
+you can use one of the installations on
+`Landfill <http://landfill.bugzilla.org/>`_.
+
+The process of creating an account is similar to many other websites.
+
+#. On the home page, click the :guilabel:`New Account` link in the header.
+   Enter your email address, then click the ``Send``
+   button.
+
+   .. note:: If the :guilabel:`New Account` link is not available, this means that the
+      administrator of the installation has disabled self-registration.
+      Speak to the administrator to find out how to get an account.
+
+#. Within moments, you should
+   receive an email to the address you provided, which contains your
+   login name (generally the same as the email address), and a URL to
+   click to confirm your registration.
+
+#. Once you confirm your registration, Bugzilla will ask you your real name
+   (optional, but recommended) and ask you to choose a password. Depending
+   on how your Bugzilla is configured, there may be minimum complexity
+   requirements for the password.
+
+#. Now all you need to do is to click the :guilabel:`Log In`
+   link in the header or footer,
+   enter your email address and the password you just chose into the
+   login form, and click the :guilabel:`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.
diff --git a/docs/en/rst/using/editing.rst b/docs/en/rst/using/editing.rst
new file mode 100644
index 000000000..c147d9d3b
--- /dev/null
+++ b/docs/en/rst/using/editing.rst
@@ -0,0 +1,98 @@
+.. _editing:
+
+Editing a Bug
+#############
+
+.. _attachments:
+
+Attachments
+===========
+
+Attachments are used to attach relevant files to bugs - patches, screenshots,
+test cases, debugging aids or logs, or anything else binary or too large to
+fit into a comment.
+
+You should use attachments, rather than comments, for large chunks of plain
+text 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 large, 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.
+
+It's also possible to create an attachment by pasting text directly in a text
+field; Bugzilla will convert it into an attachment. This is pretty useful
+when you are copying and pasting, to avoid the extra step of saving the text
+in a temporary file.
+
+.. _editing-flags:
+
+Flags
+=====
+
+To set a flag, select either :guilabel:`+` or :guilabel:`-` from the drop-down
+menu next to the name of the flag in the :guilabel:`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 :guilabel:`review`
+:guilabel:`+` may indicate that the bug/attachment has passed review, while
+setting it to :guilabel:`-` 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 :guilabel:`?` 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.
+
+.. _time-tracking:
+
+Time Tracking
+=============
+
+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 is
+marked as VERIFIED.
+
+.. _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:`workflow`).
+The image below 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.
+
+.. image:: ../../images/bzLifecycle.png
diff --git a/docs/en/rst/using/filing.rst b/docs/en/rst/using/filing.rst
new file mode 100644
index 000000000..788cebbd5
--- /dev/null
+++ b/docs/en/rst/using/filing.rst
@@ -0,0 +1,82 @@
+.. _filing:
+
+Filing a Bug
+############
+
+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 and 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.
+
+.. 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/>`_. Please don't do it on anyone's
+   production Bugzilla installation.
+
+The procedure for filing a bug is as follows:
+
+#. Click the :guilabel:`New` link available in the header or footer
+   of pages, or the :guilabel:`File a Bug` link on the home page.
+
+#. First, you 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 :guilabel:`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 also need to provide 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.
+   In the Description, give a 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 
+      Description. 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 :guilabel:`Submit Bug` button to add your report into the database.
+
+.. _cloning-a-bug:
+
+Clone an Existing Bug
+=====================
+
+Bugzilla allows you to "clone" an existing bug. The newly created bug will
+inherit most settings from the old bug. This allows you to track similar
+concerns that require different handling in a new bug. To use this, go to
+the bug that you want to clone, then click the :guilabel:`Clone This Bug`
+link on the bug page. This will take you to the :guilabel:`Enter Bug`
+page that is filled with the values that the old bug has.
+You can then change the values and/or text if needed.
diff --git a/docs/en/rst/using/finding.rst b/docs/en/rst/using/finding.rst
new file mode 100644
index 000000000..414e30cba
--- /dev/null
+++ b/docs/en/rst/using/finding.rst
@@ -0,0 +1,266 @@
+.. _finding:
+
+Finding Bugs
+############
+
+Bugzilla has a number of different search options.
+
+.. note:: 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.
+
+.. _quicksearch:
+
+Quicksearch
+===========
+
+Quicksearch is a single-text-box query tool. You'll find it in
+Bugzilla's header or footer.
+
+Quicksearch 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 also use it to go directly to a bug by entering its number or its
+alias.
+
+.. todo:: Need to incorporate the full reference, and link it properly from
+          the GUI. https://bugzilla.mozilla.org/page.cgi?id=quicksearch.html
+          Turn this item into a bug after checkin.
+
+Simple Search
+=============
+
+Simple Search is good for finding one particular bug. It works like internet
+search engines - just enter some keywords and off you go.
+
+Advanced Search
+===============
+
+The Advanced Search page is used to produce a list of all bugs fitting
+exact criteria. `You can play with it on
+Landfill <http://landfill.bugzilla.org/bugzilla-tip/query.cgi?format=advanced>`_.
+
+Advanced Search 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:`saved-searches` for more details.
+
+.. _custom-search:
+
+Custom Search
+=============
+
+Highly advanced querying is done using the Custom Search feature of the
+Advanced Search page.
+
+The search criteria here further restrict the set of results
+returned by a query over and above those defined in the fields at the top
+of the page. It is thereby possible to search for bugs
+based on elaborate combinations of criteria.
+
+The simplest boolean searches have only one term. These searches
+permit the selected *field*
+to be compared using a
+selectable *operator* to a
+specified *value.* Much of this could be reproduced using the standard
+fields. However, you can then combine terms using "Match ANY" or "Match ALL",
+using parentheses for combining and priority, in order to construct searches
+of almost arbitrary complexity.
+
+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
+
+.. _negation:
+
+.. _multiplecharts:
+
+Multiple Charts
+---------------
+
+.. todo:: This needs rewriting for the new UI.
+          Turn this item into a bug after checkin.
+          
+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.
+
+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.
+
+.. _pronouns:
+
+Pronoun Substitution
+--------------------
+
+Sometimes, a query needs to compare a user-related field
+(such as Reporter) with a role-specific user (such as the
+user running the query or the user to whom each bug is assigned). For
+example, you may want to find all bugs which are assigned to the person
+who reported them.
+
+When the Custom Search 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%".
+
+.. _list:
+
+Bug Lists
+=========
+
+The result of a search is a list of matching bugs.
+
+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
+    appears in the bug list, this link is displayed and lets you easily 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 and Removing Tags on Bugs
+================================
+
+.. todo:: Looks like you can no longer do this from search results; is that right?
+          Turn this item into a bug after checkin.
+          
+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.
diff --git a/docs/en/rst/using/index.rst b/docs/en/rst/using/index.rst
new file mode 100644
index 000000000..f336b3729
--- /dev/null
+++ b/docs/en/rst/using/index.rst
@@ -0,0 +1,18 @@
+.. _using:
+
+==========
+User Guide
+==========
+
+.. toctree::
+   :maxdepth: 2
+
+   creating-an-account
+   filing
+   understanding
+   editing
+   finding
+   reports-and-charts
+   tips
+   preferences
+
diff --git a/docs/en/rst/using/preferences.rst b/docs/en/rst/using/preferences.rst
new file mode 100644
index 000000000..d61dc4f8a
--- /dev/null
+++ b/docs/en/rst/using/preferences.rst
@@ -0,0 +1,195 @@
+.. _user-preferences:
+
+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 a number of tabs, detailed in the sections
+below.
+
+.. _generalpreferences:
+
+General Preferences
+===================
+
+This tab allows you to change several default settings of Bugzilla.
+Administrators have the power to remove preferences from this list, so you
+may not see all the preferences available.
+
+Each preference should be self-explanatory.
+
+.. _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, assignee, QA contact (if enabled)
+or CC list member.
+
+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
+uncheck 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 ``User 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.
+
+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.
+
+Lastly, you can define a list of bugs on which you no longer wish to receive
+any email, ever. (You can also add bugs to this list individually by checking
+the "Ignore Bug Mail" checkbox on the bug page for that bug.) This is useful
+for ignoring bugs where you are the reporter, as that's a role it's not
+possible to stop having.
+
+.. _saved-searches:
+
+Saved Searches
+==============
+
+On this tab you can view and run any Saved Searches that you have
+created, and any Saved Searches that other members of the group
+defined in the :param:`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 they are 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.
+
+.. _account-information:
+
+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.
+
+.. _api-keys:
+
+API Keys
+========
+
+API keys allow you to give a "token" to some external software so it can log
+in to the WebService API as you without knowing your password. You can then
+revoke that token if you stop using the web service, and you don't need to
+change your password everywhere.
+
+You can create more than one API key if required. Each API key has an optional
+description which can help you record what it 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 is optional and purely for your information.
+
+You can also create a new API key by selecting the checkbox under the 'New
+API key' section of the page.
+
+.. _permissions:
+
+Permissions
+===========
+
+This is a purely informative page which outlines your current
+permissions on this installation of Bugzilla.
+
+A complete list of permissions in a default install of Bugzilla is below.
+Your administrator may have defined other permissions. 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 products, components,
+    versions, milestones and flag types.
+
+editkeywords
+    Indicates user can create, destroy and edit keywords.
+
+editusers
+    Indicates user can create, disable and edit users.
+
+tweakparams
+    Indicates user can change :ref:`Parameters <parameters>`.
diff --git a/docs/en/rst/using/reports-and-charts.rst b/docs/en/rst/using/reports-and-charts.rst
new file mode 100644
index 000000000..659cd5cbd
--- /dev/null
+++ b/docs/en/rst/using/reports-and-charts.rst
@@ -0,0 +1,120 @@
+.. _reports-and-charts:
+
+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 :guilabel:`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 :guilabel:`Category` and Component names as :guilabel:`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 :guilabel:`Category` be your username.
+
+Creating Charts
+---------------
+
+You create a chart by selecting a number of data sets from the
+list and pressing :guilabel:`Add To List` for each. In the
+:guilabel:`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 :guilabel:`Sum`
+a number of data sets (e.g. you could :guilabel:`Sum` data sets representing
+:guilabel:`RESOLVED`, :guilabel:`VERIFIED` and :guilabel:`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 :guilabel:`Remove`. Once you add more than one
+data set, a :guilabel:`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, you can also perform certain
+actions on it. For example, you 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 :guilabel:`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 :guilabel:`create a new data set` link on the
+:guilabel:`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
+of seven days.
+
diff --git a/docs/en/rst/using/tips.rst b/docs/en/rst/using/tips.rst
new file mode 100644
index 000000000..a48149275
--- /dev/null
+++ b/docs/en/rst/using/tips.rst
@@ -0,0 +1,92 @@
+.. _pro-tips:
+
+Pro 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 bugmail.
+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.
+
+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.
+
+.. _markdown:
+
+Markdown
+--------
+
+Markdown is a structured plain-text format which lets you write comments that
+have more styling than plain text. 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 <https://bugzilla.mozilla.org/page.cgi?id=markdown.html>`_ link
+next to the Markdown checkbox for new comments.
+
+.. todo:: The above link isn't ideal, but we can't easily link to the user's
+          Bugzilla because the docs aren't always on a Bugzilla (e.g.
+          when they are on ReadTheDocs). Best solution is to port the
+          Markdown guide to ReST.
+          Turn this item into a bug after checkin.
+          
+To use the Markdown feature, make sure that :guilabel:`Enable Markdown
+support for comments` is set to :guilabel:`on`
+in your :ref:`user-preferences` and that you also check the :guilabel:`Use
+Markdown for this comment` option below the comment box when you want to
+submit a new comment which uses Markdown.
diff --git a/docs/en/rst/using/understanding.rst b/docs/en/rst/using/understanding.rst
new file mode 100644
index 000000000..014abefd6
--- /dev/null
+++ b/docs/en/rst/using/understanding.rst
@@ -0,0 +1,302 @@
+.. _understanding:
+
+Understanding a Bug
+###################
+
+The core of Bugzilla is the screen which displays a particular
+bug. 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.
+
+*Summary:*
+   A one-sentence summary of the problem, displayed in the header next to
+   the bug number.
+
+*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.
+
+*Alias:*
+   A unique short text name for the bug, which can be used instead of the
+   bug number.
+
+*Product and Component*:
+   Bugs are divided up by Product and Component, with a Product
+   having one or more Components in it. 
+
+*Version:*
+   The "Version" field usually contains the numbers or names of released
+   versions of the product. It is used to indicate the version(s) affected by
+   the bug report.
+
+*Hardware (Platform and OS):*
+   These indicate the computing environment where the bug was
+   found.
+
+*Importance (Priority and Severity):*
+   The Priority field is used to prioritize bugs, either by the assignee,
+   or someone else with authority to direct their time such as a project
+   manager. It's a good idea not to change this on other people's bugs. The
+   default values are P1 to P5.
+
+   The Severity field 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 Milestone:*
+   A future version by which the bug is to
+   be fixed. e.g. The Bugzilla Project's milestones for future
+   Bugzilla versions are 4.4, 5.0, 6.0, etc. Milestones are not
+   restricted to numbers, though—you can use any text strings, such
+   as dates.
+
+*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.
+
+*\*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. ``crash`` or ``regression``.
+
+*Personal Tags:*
+   Unlike Keywords which are global and visible by all users, Personal Tags
+   are personal and can only be viewed and edited by their author. Editing
+   them won't send any notification to other users. Use them to tag and keep
+   track of bugs. 
+
+*Dependencies (Depends On and Blocks):*
+   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.
+
+   Clicking the :guilabel:`Dependency tree` link shows
+   the dependency relationships of 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 collapse/expand dependencies for
+   each non-terminal bug on the tree view, using the [-]/[+] buttons that
+   appear before the summary.
+
+*Reported:*
+   The person who filed the bug, and the date and time they did it.
+
+*Modified:*
+   The date and time the bug was last changed.
+
+*CC List:*
+   A list of people who get mail when the bug changes, in addition to the
+   Reporter, Assignee and QA Contact (if enabled).
+
+*Ignore Bug Mail:*
+   Set this if you want never to get bugmail from this bug again. See also
+   :ref:`emailpreferences`.
+
+*\*See Also:*
+   Bugs, in this Bugzilla, other Bugzillas, or other bug trackers, that are
+   related to this one.
+
+*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. See :ref:`flags`.
+
+*\*Time Tracking:*
+   This form can be used for time tracking.
+   To use this feature, you have to be a member of the group
+   specified by the :param:`timetrackinggroup` parameter. See
+   :ref:`time-tracking` for more information.
+
+   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. test cases or patches) to bugs. If there
+   are any attachments, they are listed in this section. See
+   :ref:`attachments` for more information.
+
+*Additional Comments:*
+   You can add your two cents to the bug discussion here, if you have
+   something worthwhile to say.
+
+.. _flags:
+
+Flags
+=====
+
+Flags are a way to attach a specific status to a bug or attachment,
+either ``+`` or ``-``. The meaning of these symbols depends on the name of
+the flag itself, but contextually they could mean pass/fail,
+accept/reject, approved/denied, or even a simple yes/no. If your site
+allows requestable flags, then users may set a flag to ``?`` as a
+request to another user that they look at the bug/attachment and set
+the flag to its correct status.
+
+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 :guilabel:`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 :guilabel:`Jack: review [ ? ] (Jill)`.
+
+You can browse through open requests made of you and by you by selecting
+:guilabel:`My Requests` from the footer. You can also look at open requests
+limited by other requesters, requestees, products, components, and flag names.
+Note that you can use '-' for requestee to specify flags with no requestee
+set.
+
+.. _flags-simpleexample:
+
+A Simple Example
+----------------
+
+A developer might want to ask their manager,
+"Should we fix this bug before we release version 2.0?"
+They might want to do this for a *lot* of bugs,
+so they decide to streamline the process. So:
+
+#. The Bugzilla administrator creates a flag type called blocking2.0 for bugs
+   in your product. It shows up on the :guilabel:`Show Bug` screen as the text
+   :guilabel:`blocking2.0` with a drop-down box next to it. The drop-down box
+   contains four values: an empty space, ``?``, ``-``, and ``+``.
+
+#. The developer sets the flag to ``?``.
+
+#. The manager sees the :guilabel:`blocking2.0`
+   flag with a ``?`` value.
+
+#. If the manager thinks the feature should go into the product
+   before version 2.0 can be released, they set the flag to
+   ``+``. Otherwise, they set it to ``-``.
+
+#. Now, every Bugzilla user who looks at the bug knows whether or
+   not the bug needs to be fixed before release of version 2.0.
+
+.. _flags-about:
+
+About Flags
+-----------
+
+Flags can have four values:
+
+``?``
+    A user is requesting that a status be set. (Think of it as 'A question is being asked'.)
+
+``-``
+    The status has been set negatively. (The question has been answered ``no``.)
+
+``+``
+    The status has been set positively.
+    (The question has been answered ``yes``.)
+
+``_``
+    ``unset`` actually shows up as a blank space. This just means that nobody
+    has expressed an opinion (or asked someone else to express an opinion)
+    about the matter covered by this flag.
+
+.. _flag-askto:
+
+Flag Requests
+-------------
+
+If a flag has been defined as :guilabel:`requestable`, and a user has enough
+privileges to request it (see below), the user can set the flag's status to
+``?``. This status indicates that someone (a.k.a. "the requester") is asking
+someone else to set the flag to either ``+`` or ``-``.
+
+If a flag has been defined as :guilabel:`specifically requestable`,
+a text box will appear next to the flag into which the requester may
+enter a Bugzilla username. That named person (a.k.a. "the requestee")
+will receive an email notifying them of the request, and pointing them
+to the bug/attachment in question.
+
+If a flag has *not* been defined as :guilabel:`specifically requestable`,
+then no such text box will appear. A request to set this flag cannot be made
+of any specific individual; these requests are open for anyone to answer. In
+Bugzilla this is known as "asking the wind". A requester may ask the wind on
+any flag simply by leaving the text box blank.
+
+.. _flag-types:
+
+.. _flag-type-attachment:
+
+Attachment Flags
+----------------
+
+There are two types of flags: bug flags and attachment flags.
+
+Attachment flags are used to ask a question about a specific
+attachment on a bug.
+
+Many Bugzilla installations use this to
+request that one developer review another
+developer's code before they check it in. They attach the code to
+a bug report, and then set a flag on that attachment called
+:guilabel:`review` to
+:guilabel:`review? reviewer@example.com`.
+reviewer\@example.com is then notified by email that
+they have to check out that attachment and approve it or deny it.
+
+For a Bugzilla user, attachment flags show up in three places:
+
+#. On the list of attachments in the :guilabel:`Show Bug`
+   screen, you can see the current state of any flags that
+   have been set to ``?``, ``+``, or ``-``. You can see who asked about
+   the flag (the requester), and who is being asked (the
+   requestee).
+
+#. When you edit an attachment, you can
+   see any settable flag, along with any flags that have
+   already been set. The :guilabel:`Edit Attachment`
+   screen is where you set flags to ``?``, ``-``, ``+``, or unset them.
+
+#. Requests are listed in the :guilabel:`Request Queue`, which
+   is accessible from the :guilabel:`My Requests` link (if you are
+   logged in) or :guilabel:`Requests` link (if you are logged out)
+   visible on all pages.
+
+.. _flag-type-bug:
+
+Bug Flags
+---------
+
+Bug flags are used to set a status on the bug itself. You can
+see Bug Flags in the :guilabel:`Show Bug` and :guilabel:`Requests`
+screens, as described above.
+
+Only users with enough privileges (see below) may set flags on bugs.
+This doesn't necessarily include the assignee, reporter, or users with the
+:group:`editbugs` permission.