From 4bbb07e8048ef859cfc29c6b9d221840f2c6aed1 Mon Sep 17 00:00:00 2001 From: "gerv%gerv.net" <> Date: Fri, 16 Jan 2004 06:34:12 +0000 Subject: Phase 1 of a big documentation update before 2.17.6. --- docs/xml/using.xml | 897 ++++++++++++++++++++++++++--------------------------- 1 file changed, 447 insertions(+), 450 deletions(-) (limited to 'docs/xml/using.xml') diff --git a/docs/xml/using.xml b/docs/xml/using.xml index f06969f57..21614e740 100644 --- a/docs/xml/using.xml +++ b/docs/xml/using.xml @@ -3,468 +3,461 @@ Using Bugzilla -
- How do I use Bugzilla? - - This section contains information for end-users of Bugzilla. - There is a Bugzilla test installation, called - Landfill, - which you are welcome to play with (if it's up.) - However, it does not necessarily - have all Bugzilla features enabled, and often runs cutting-edge versions - of Bugzilla for testing, so some things may work slightly differently - than mentioned here. - -
- Create a Bugzilla Account - - If you want to use Bugzilla, first you need to create an account. - Consult with the administrator responsible for your installation of - Bugzilla for the URL you should use to access it. If you're - test-driving Bugzilla, use this URL: - . - - - - - Click the - Open a new Bugzilla account - - link, enter your email address and, optionally, your name in the - spaces provided, then click - Create Account - - . - - - - Within moments, you should receive an email to the address - you provided above, which contains your login name (generally the - same as the email address), and a password you can use to access - your account. This password is randomly generated, and can be - changed to something more memorable. - - - - Click the - Log In - link in the yellow area at the bottom of the page in your browser, - enter your email address and password into the spaces provided, and - click - Login. - - - - - - You are now logged in. Bugzilla uses cookies for authentication - so, unless your IP address changes, you should not have to log in - again. -
+ This section contains information for end-users of Bugzilla. + There is a Bugzilla test installation, called + Landfill, + which you are welcome to play with (if it's up.) + However, it does not necessarily + have all Bugzilla features enabled, and runs an up-to-the-minute version, + so some things may not quite work as this document describes. + +
+ Create a Bugzilla Account + + If you want to use Bugzilla, first you need to create an account. + Consult with the administrator responsible for your installation of + Bugzilla for the URL you should use to access it. If you're + test-driving Bugzilla, use this URL: + . + + + + + Click the + Open a new Bugzilla account + + link, enter your email address and, optionally, your name in the + spaces provided, then click + Create 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 password. + This password is randomly generated, but can be + changed to something more memorable. + + + + Click the + Log In + link in the footer at the bottom of the page in your browser, + enter your email address and password into the spaces provided, and + click + Login. + + + + + + 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. +
-
- Anatomy of a Bug - - The core of Bugzilla is the screen which displays a particular - bug. It's a good place to explain some Bugzilla concepts. - - Bug 1 on Landfill - - is a good example. Note that the labels for most fields are hyperlinks; - clicking them will take you to context-sensitive help on that - particular field. Fields marked * may not be present on every - installation of Bugzilla. - - - - - Product and Component: - Bugs are divided up by Product and Component, with a Product - having one or more Components in it. For example, - bugzilla.mozilla.org's "Bugzilla" Product is composed of several - Components: - - - Administration: - Administration of a Bugzilla installation. - - - Bugzilla-General: - Anything that doesn't fit in the other components, or spans - multiple components. - - - Creating/Changing Bugs: - Creating, changing, and viewing bugs. - - - Documentation: - The Bugzilla documentation, including The Bugzilla Guide. - - - Email: - Anything to do with email sent by Bugzilla. - - - Installation: - The installation process of Bugzilla. - - - Query/Buglist: - Anything to do with searching for bugs and viewing the - buglists. - - - Reporting/Charting: - Getting reports from Bugzilla. - - - User Accounts: - Anything about managing a user account from the user's perspective. - Saved queries, creating accounts, changing passwords, logging in, - etc. - - - User Interface: - General issues having to do with the user interface cosmetics (not - functionality) including cosmetic issues, HTML templates, - etc. - - - - - - - Status and Resolution: - - These define exactly what state the bug is in - from not even - being confirmed as a bug, through to being fixed and the fix - confirmed by Quality Assurance. The different possible values for - Status and Resolution on your installation should be documented in the - context-sensitive help for those items. - - - - - Assigned To: - The person responsible for fixing the bug. - - - - - *URL: - A URL associated with the bug, if any. - - - - - Summary: - A one-sentence summary of the problem. - - - - - *Status Whiteboard: - (a.k.a. Whiteboard) A free-form text area for adding short notes - and tags to a bug. - - - - - *Keywords: - The administrator can define keywords which you can use to tag and - categorise bugs - e.g. The Mozilla Project has keywords like crash - and regression. - - - - - Platform and OS: - These indicate the computing environment where the bug was - found. - - - - - Version: - The "Version" field is usually used for versions of a product which - have been released, and is set to indicate which versions of a - Component have the particular problem the bug report is - about. - - - - - Priority: - The bug assignee uses this field to prioritise his or her bugs. - It's a good idea not to change this on other people's bugs. - - - - - Severity: - This indicates how severe the problem is - from blocker - ("application unusable") to trivial ("minor cosmetic issue"). You - can also use this field to indicate whether a bug is an enhancement - request. - - - - - *Target: - (a.k.a. Target Milestone) A future version by which the bug is to - be fixed. e.g. The Bugzilla Project's milestones for future - Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not - restricted to numbers, thought - you can use any text strings, such - as dates. - - - - - Reporter: - The person who filed the bug. - - - - - CC list: - A list of people who get mail when the bug changes. - - - - - Attachments: - You can attach files (e.g. testcases or patches) to bugs. If there - are any attachments, they are listed in this section. - - - - - *Dependencies: - If this bug cannot be fixed unless other bugs are fixed (depends - on), or this bug stops other bugs being fixed (blocks), their - numbers are recorded here. - - - - - *Votes: - Whether this bug has any votes. - - - - - Additional Comments: - You can add your two cents to the bug discussion here, if you have - something worthwhile to say. - - -
+
+ Anatomy of a Bug + + The core of Bugzilla is the screen which displays a particular + bug. It's a good place to explain some Bugzilla concepts. + + Bug 1 on Landfill + + is a good example. Note that the labels for most fields are hyperlinks; + clicking them will take you to context-sensitive help on that + particular field. Fields marked * may not be present on every + installation of Bugzilla. + + + + + Product and Component: + Bugs are divided up by Product and Component, with a Product + having one or more Components in it. For example, + bugzilla.mozilla.org's "Bugzilla" Product is composed of several + Components: + + + Administration: + Administration of a Bugzilla installation. -
- Searching for Bugs + + Bugzilla-General: + Anything that doesn't fit in the other components, or spans + multiple components. - The Bugzilla Search page is is the interface where you can find - any bug report, comment, or patch currently in the Bugzilla system. You - can play with it here: - . + + Creating/Changing Bugs: + Creating, changing, and viewing bugs. - The Search page has controls for selecting different possible - values for all of the fields in a bug, as described above. For some - fields, multiple values can be selected. In those cases, Bugzilla - returns bugs where the content of the field matches one of the selected - values. If none is selected, then the field can take any value. - - Once you've defined a search, you can either run it, or save it - as a Remembered Query, which can optionally appear in the footer of - your pages. + + Documentation: + The Bugzilla documentation, including The Bugzilla Guide. - Highly advanced querying is done using Boolean Charts. -
+ + Email: + Anything to do with email sent by Bugzilla. -
- Bug Lists + + Installation: + The installation process of Bugzilla. - If you run a search, a list of matching bugs will be returned. - The default search is to return all open bugs on the system - don't try - running this search on a Bugzilla installation with a lot of - bugs! + + Query/Buglist: + Anything to do with searching for bugs and viewing the + buglists. - 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: + Reporting/Charting: + Getting reports from Bugzilla. - this gives you a large page with a non-editable summary of the fields - of each bug. + + User Accounts: + Anything about managing a user account from the user's perspective. + Saved queries, creating accounts, changing passwords, logging in, + etc. - Change Columns: + User Interface: + General issues having to do with the user interface cosmetics (not + functionality) including cosmetic issues, HTML templates, + etc. + + + + + + + Status and Resolution: + + These define exactly what state the bug is in - from not even + being confirmed as a bug, through to being fixed and the fix + confirmed by Quality Assurance. The different possible values for + Status and Resolution on your installation should be documented in the + context-sensitive help for those items. + + + + + Assigned To: + The person responsible for fixing the bug. + + + + + *URL: + A URL associated with the bug, if any. + + + + + Summary: + A one-sentence summary of the problem. + + + + + *Status Whiteboard: + (a.k.a. Whiteboard) A free-form text area for adding short notes + and tags to a bug. + + + + + *Keywords: + The administrator can define keywords which you can use to tag and + categorise bugs - e.g. The Mozilla Project has keywords like crash + and regression. + + + + + Platform and OS: + These indicate the computing environment where the bug was + found. + + + + + Version: + The "Version" field is usually used for versions of a product which + have been released, and is set to indicate which versions of a + Component have the particular problem the bug report is + about. + + + + + Priority: + The bug assignee uses this field to prioritise his or her bugs. + It's a good idea not to change this on other people's bugs. + + + + + Severity: + This indicates how severe the problem is - from blocker + ("application unusable") to trivial ("minor cosmetic issue"). You + can also use this field to indicate whether a bug is an enhancement + request. + + + + + *Target: + (a.k.a. Target Milestone) A future version by which the bug is to + be fixed. e.g. The Bugzilla Project's milestones for future + Bugzilla versions are 2.18, 2.20, 3.0, etc. Milestones are not + restricted to numbers, thought - you can use any text strings, such + as dates. + + + + + Reporter: + The person who filed the bug. + + + + + CC list: + A list of people who get mail when the bug changes. + + + + + Attachments: + You can attach files (e.g. testcases or patches) to bugs. If there + are any attachments, they are listed in this section. + + + + + *Dependencies: + If this bug cannot be fixed unless other bugs are fixed (depends + on), or this bug stops other bugs being fixed (blocks), their + numbers are recorded here. + + + + + *Votes: + Whether this bug has any votes. + + + + + Additional Comments: + You can add your two cents to the bug discussion here, if you have + something worthwhile to say. + + +
- change the bug attributes which appear in the list. +
+ Searching for Bugs - - Change several bugs at once: + The Bugzilla Search page is is the interface where you can find + any bug report, comment, or patch currently in the Bugzilla system. You + can play with it here: + . - If your account is sufficiently empowered, you can make the same - change to all the bugs in the list - for example, changing their - owner. + The Search page has controls for selecting different possible + values for all of the fields in a bug, as described above. For some + fields, multiple values can be selected. In those cases, Bugzilla + returns bugs where the content of the field matches any one of the selected + values. If none is selected, then the field can take any value. - - Send mail to bug owners: + Once you've run a search, you can save it as a Saved Search, which + appears in the page footer. + + Highly advanced querying is done using Boolean Charts. See the + Boolean Charts help link on the Search page for more information. +
- Sends mail to the owners of all bugs on the list. +
+ Bug Lists - - Edit this query: + If you run a search, a list of matching bugs will be returned. + - 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. - - -
+ 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: -
- Filing Bugs + this gives you a large page with a non-editable summary of the fields + of each bug. + + + Change Columns: - Years of bug writing experience has been distilled for your - reading pleasure into the - - Bug Writing Guidelines. - While some of the advice is Mozilla-specific, the basic principles of - reporting Reproducible, Specific bugs, isolating the Product you are - using, the Version of the Product, the Component which failed, the - Hardware Platform, and Operating System you were using at the time of - the failure go a long way toward ensuring accurate, responsible fixes - for the bug that bit you. - - The procedure for filing a test bug is as follows: - - - - Go to - - Landfill - in your browser and click - - Enter a new bug report. - - - - - Select a product - any one will do. - - - - Fill in the fields. Bugzilla should have made reasonable - guesses, based upon your browser, for the "Platform" and "OS" - drop-down boxes. If they are wrong, change them. - - - - Select "Commit" and send in your bug report. - - + change the bug attributes which appear in the list. + + + Change several bugs at once: + + If your account is sufficiently empowered, you can make the same + change to all the bugs in the list - for example, changing their + owner. + + + Send mail to bug owners: + + Sends mail to the owners of all bugs on the list. + + + Edit this query: + + 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. + + +
+ +
+ Filing Bugs + + Years of bug writing experience has been distilled for your + reading pleasure into the + + Bug Writing Guidelines. + While some of the advice is Mozilla-specific, the basic principles of + reporting Reproducible, Specific bugs, isolating the Product you are + using, the Version of the Product, the Component which failed, the + Hardware Platform, and Operating System you were using at the time of + the failure go a long way toward ensuring accurate, responsible fixes + for the bug that bit you. + + The procedure for filing a test bug is as follows: + + + + Go to + + Landfill + in your browser and click + + Enter a new bug report. + + + + + Select a product - any one will do. + + + + Fill in the fields. Bugzilla should have made reasonable + guesses, based upon your browser, for the "Platform" and "OS" + drop-down boxes. If they are wrong, change them. + + + + Select "Commit" and send in your bug report. + + +
+ +
+ Patch Viewer + + Viewing and reviewing patches in Bugzilla is often difficult due to + lack of context, improper format and the inherent readability issues that + raw patches present. Patch Viewer is an enhancement to Bugzilla designed + to fix that by offering increased context, linking to sections, and + integrating with Bonsai, LXR and CVS. + + Patch viewer allows you to: + + + View patches in color, with side-by-side view rather than trying + to interpret the contents of the patch. + See the difference between two patches. + Get more context in a patch. + Collapse and expand sections of a patch for easy + reading. + Link to a particular section of a patch for discussion or + review + Go to Bonsai or LXR to see more context, blame, and + cross-references for the part of the patch you are looking at + Create a rawtext unified format diff out of any patch, no + matter what format it came from + + +
+ Viewing Patches in Patch Viewer + The main way to view a patch in patch viewer is to click on the + "Diff" link next to a patch in the Attachments list on a bug. You may + also do this within the edit window by clicking the "View Attachment As + Diff" button in the Edit Attachment screen.
-
- Patch Viewer +
+ Seeing the Difference Between Two Patches + To see the difference between two patches, you must first view the + newer patch in Patch Viewer. Then select the older patch from the + dropdown at the top of the page ("Differences between [dropdown] and + this patch") and click the "Diff" button. This will show you what + is new or changed in the newer patch. +
- Viewing and reviewing patches in Bugzilla is often difficult due to - lack of context, improper format and the inherent readability issues that - raw patches present. Patch Viewer is an enhancement to Bugzilla designed - to fix that by offering increased context, linking to sections, and - integrating with Bonsai, LXR and CVS. +
+ Getting More Context in a Patch + To get more context in a patch, you put a number in the textbox at + the top of Patch Viewer ("Patch / File / [textbox]") and hit enter. + This will give you that many lines of context before and after each + change. Alternatively, you can click on the "File" link there and it + will show each change in the full context of the file. This feature only + works against files that were diffed using "cvs diff". +
- Patch viewer allows you to: +
+ Collapsing and Expanding Sections of a Patch + To view only a certain set of files in a patch (for example, if a + patch is absolutely huge and you want to only review part of it at a + time), you can click the "(+)" and "(-)" links next to each file (to + expand it or collapse it). If you want to collapse all files or expand + all files, you can click the "Collapse All" and "Expand All" links at the + top of the page. +
- - View patches in color, with side-by-side view rather than trying - to interpret the contents of the patch. - See the difference between two patches. - Get more context in a patch. - Collapse and expand sections of a patch for easy - reading. - Link to a particular section of a patch for discussion or - review - Go to Bonsai or LXR to see more context, blame, and - cross-references for the part of the patch you are looking at - Create a rawtext unified format diff out of any patch, no - matter what format it came from - + -
- Viewing Patches in Patch Viewer - The main way to view a patch in patch viewer is to click on the - "Diff" link next to a patch in the Attachments list on a bug. You may - also do this within the edit window by clicking the "View Attachment As - Diff" button in the Edit Attachment screen. -
- -
- Seeing the Difference Between Two Patches - To see the difference between two patches, you must first view the - newer patch in Patch Viewer. Then select the older patch from the - dropdown at the top of the page ("Differences between [dropdown] and - this patch") and click the "Diff" button. This will show you what - is new or changed in the newer patch. -
- -
- Getting More Context in a Patch - To get more context in a patch, you put a number in the textbox at - the top of Patch Viewer ("Patch / File / [textbox]") and hit enter. - This will give you that many lines of context before and after each - change. Alternatively, you can click on the "File" link there and it - will show each change in the full context of the file. This feature only - works against files that were diffed using "cvs diff". -
- -
- Collapsing and Expanding Sections of a Patch - To view only a certain set of files in a patch (for example, if a - patch is absolutely huge and you want to only review part of it at a - time), you can click the "(+)" and "(-)" links next to each file (to - expand it or collapse it). If you want to collapse all files or expand - all files, you can click the "Collapse All" and "Expand All" links at the - top of the page. -
- - - -
- Going to Bonsai and LXR - To go to Bonsai to get blame for the lines you are interested in, - you can click the "Lines XX-YY" link on the section header you are - interested in. This works even if the patch is against an old - version of the file, since Bonsai stores all versions of the file. - - To go to LXR, you click on the filename on the file header - (unfortunately, since LXR only does the most recent version, line - numbers are likely to rot). -
- -
- Creating a Unified Diff - If the patch is not in a format that you like, you can turn it - into a unified diff format by clicking the "Raw Unified" link at the top - of the page. -
+
+ Going to Bonsai and LXR + To go to Bonsai to get blame for the lines you are interested in, + you can click the "Lines XX-YY" link on the section header you are + interested in. This works even if the patch is against an old + version of the file, since Bonsai stores all versions of the file. + + To go to LXR, you click on the filename on the file header + (unfortunately, since LXR only does the most recent version, line + numbers are likely to rot). +
+
+ Creating a Unified Diff + If the patch is not in a format that you like, you can turn it + into a unified diff format by clicking the "Raw Unified" link at the top + of the page.
+
@@ -475,15 +468,16 @@
Autolinkification - Bugzilla comments are plain text - so posting HTML will result - in literal HTML tags rather than being interpreted by a browser. + 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 + "http://www.bugzilla.org" will be turned into a link: . Other strings which get linkified in the obvious manner are: bug 12345 + comment 7 bug 23456, comment 53 attachment 4321 mailto:george@example.com @@ -532,7 +526,7 @@ Don't use sigs in comments. Signing your name ("Bill") is acceptable, - particularly if you do it out of habit, but full mail/news-style + if you do it out of habit, but full mail/news-style four line ASCII art creations are not.
@@ -586,7 +580,7 @@ Once you have logged in, you can customise various aspects of Bugzilla via the "Edit prefs" link in the page footer. - The preferences are split into four tabs: + The preferences are split into three tabs:
Account Settings @@ -608,9 +602,16 @@ On this tab you can reduce or increase the amount of email sent you from Bugzilla, opting in our out depending on your relationship to - the bug and the change that was made to it. (Note that you can also do - client-side filtering using the X-Bugzilla-Reason header which Bugzilla - adds to all bugmail.) + the bug and the change that was made to it. + + + + You can also do further filtering on the client side by + using the X-Bugzilla-Reason mail header which Bugzilla + adds to all bugmail. This tells you what relationship you have to the + bug in question, + and can be any of Owner, Reporter, QAcontact, CClist, Voter and + WatchingComponent. By entering user email names, delineated by commas, into the "Users to watch" text entry box you can receive a copy of all the @@ -625,15 +626,6 @@
-
- Page Footer - - On the Search page, you can store queries in Bugzilla, so if you - regularly run a particular query it is just a drop-down menu away. - Once you have a stored query, you can come - here to request that it also be displayed in your page footer. -
-
Permissions @@ -643,6 +635,11 @@ functions.
+
+ Reports + To be written +
+