diff options
Diffstat (limited to 'docs/en/rst/using')
| -rw-r--r-- | docs/en/rst/using/creating-an-account.rst | 39 | ||||
| -rw-r--r-- | docs/en/rst/using/editing.rst | 98 | ||||
| -rw-r--r-- | docs/en/rst/using/filing.rst | 82 | ||||
| -rw-r--r-- | docs/en/rst/using/finding.rst | 266 | ||||
| -rw-r--r-- | docs/en/rst/using/index.rst | 18 | ||||
| -rw-r--r-- | docs/en/rst/using/preferences.rst | 195 | ||||
| -rw-r--r-- | docs/en/rst/using/reports-and-charts.rst | 120 | ||||
| -rw-r--r-- | docs/en/rst/using/tips.rst | 92 | ||||
| -rw-r--r-- | docs/en/rst/using/understanding.rst | 302 |
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. |