diff --git a/en_US.ISO8859-1/articles/problem-reports/article.sgml b/en_US.ISO8859-1/articles/problem-reports/article.sgml index f9bec866b8..9b8b826a33 100644 --- a/en_US.ISO8859-1/articles/problem-reports/article.sgml +++ b/en_US.ISO8859-1/articles/problem-reports/article.sgml @@ -38,11 +38,12 @@ FreeBSD Entities//EN"> %freebsd; One of the most frustrating experiences one can have as a software user is to submit a problem report only to have it summarily closed with a terse and unhelpful explanation like - "not a bug" or "bogus PR". Similarly, one of the most - frustrating experiences as a software developer is to be flooded - with problem reports that are not really problem reports but - requests for support, or that contain little or no information - about what the problem is and how to reproduce it. + not a bug or bogus PR. Similarly, + one of the most frustrating experiences as a software developer + is to be flooded with problem reports that are not really + problem reports but requests for support, or that contain little + or no information about what the problem is and how to reproduce + it. This document attempts to describe how to write good problem reports. What, you ask, is a good problem report? Well, to go @@ -56,8 +57,8 @@ FreeBSD Entities//EN"> %freebsd; Note that this article is organized thematically, not chronologically, so you should read through the entire document - before submitting a PR, rather than treat it as a step-by-step - tutorial. + before submitting a problem report, rather than treat it as a + step-by-step tutorial. @@ -65,31 +66,31 @@ FreeBSD Entities//EN"> %freebsd; There are many types of problems, and not all of them should engender a problem report. Of course, nobody is perfect, and - there will be times when you are convinced you've found a bug in - a program when in fact you've misunderstood the syntax for a - command or made a typo in a configuration file (though that in + there will be times when you are convinced you have found a bug + in a program when in fact you have misunderstood the syntax for + a command or made a typo in a configuration file (though that in itself may sometimes be indicative of poor documentation or poor error handling in the application). There are still many cases where submitting a problem report is clearly not the right course of action, and will only serve to frustrate you and the developers. Conversely, there are cases where it might be appropriate to submit a problem report about something else than - a bug — an enhancement or a feature request, for + a bug—an enhancement or a feature request, for instance. - So how do you determine what's a bug and what is not? As a + So how do you determine what is a bug and what is not? As a simple rule of thumb your problem is not a bug if it can be expressed as a question (usually of the form - "How do I do X?" or "Where can I find Y?"). It's not always - quite so black and white, but the question rule covers a large - majority of cases. + How do I do X? or Where can I find + Y?). It is not always quite so black and white, but the + question rule covers a large majority of cases. Some cases where it may be appropriate to submit a problem report about something that is not a bug are: - Requests for feature enhancments. It is generally a + Requests for feature enhancements. It is generally a good idea to air these on the mailing lists before submitting a problem report. @@ -109,14 +110,14 @@ FreeBSD Entities//EN"> %freebsd; that will annoy a developer more than receiving a problem report about a bug she's already fixed. - Finally, a bug that can't be reproduced can rarely be fixed. - If the bug only occurred once and you can't reproduce it, and it - doesn't seem to happen to anybody else, chances are none of the - developers will be able to reproduce it or figure out what's - wrong. That doesn't mean it didn't happen, but it does mean - that the chances of your problem report ever leading to a bug - fix are very slim, and you should consider letting the matter - drop. + Finally, a bug that can not be reproduced can rarely be + fixed. If the bug only occurred once and you can not reproduce + it, and it does not seem to happen to anybody else, chances are + none of the developers will be able to reproduce it or figure + out what's wrong. That does not mean it did not happen, but it + does mean that the chances of your problem report ever leading + to a bug fix are very slim, and you should consider letting the + matter drop. @@ -124,11 +125,11 @@ FreeBSD Entities//EN"> %freebsd; A good rule to follow is to always do a background search before submitting a problem report. Maybe your problem has - already been reported; maybe it's being discussed on the mailing - lists, or recently was; it may even already be fixed in a newer - version than what you're running. You should therefore check - all the obvious places before submitting your PR. For FreeBSD, - this means: + already been reported; maybe it is being discussed on the + mailing lists, or recently was; it may even already be fixed in + a newer version than what you are running. You should therefore + check all the obvious places before submitting your problem + report. For FreeBSD, this means: @@ -136,24 +137,24 @@ FreeBSD Entities//EN"> %freebsd; - The mailing lists — if you're not subscribed, use + The mailing lists—if you're not subscribed, use the searchable archives on the FreeBSD web site. If your - problem hasn't been discussed on the lists, you might try + problem has not been discussed on the lists, you might try posting a message about it and waiting a few days to see if - someone can spot something you've overlooked. + someone can spot something you have overlooked. - Optionally, the entire web — use your favorite + Optionally, the entire web—use your favorite search engine to locate any references to your problem. You may even get hits from archived mailing lists or newsgroups - you didn't know of or hadn't thought to search + you did not know of or had not thought to search through. Finally, the FreeBSD PR database. Unless your problem - is recent or obscure, there's a fair chance it's already + is recent or obscure, there is a fair chance it has already been reported. @@ -169,12 +170,12 @@ FreeBSD Entities//EN"> %freebsd; problem may lie in how the software was ported to FreeBSD; the second is if the original author has already fixed the bug and released a patch or a new version of his software, and the - FreeBSD port hasn't been updated yet. + FreeBSD port has not been updated yet. The second catch is that FreeBSD's bug tracking system sorts problem reports according to the category the originator selected. Therefore, if you select the wrong category when you - submit your problem report, there's a good chance that it will + submit your problem report, there is a good chance that it will go unnoticed for a while, until someone re-categorizes it. @@ -182,10 +183,10 @@ FreeBSD Entities//EN"> %freebsd; Writing the problem report - Now that you've decided that your issue merits a problem - report, and that it's a FreeBSD problem, it's time to write the - actual PR. Make sure your VISUAL (or - EDITOR if VISUAL is not set) + Now that you have decided that your issue merits a problem + report, and that it is a FreeBSD problem, it is time to write + the actual problem report. Make sure your VISUAL + (or EDITOR if VISUAL is not set) environment variable is set to something sensible, and run &man.send-pr.1;. @@ -198,13 +199,13 @@ FreeBSD Entities//EN"> %freebsd; name of the file proper, without the path). Just use the command-line option to specify the names of the files you wish to attach: - + &prompt.user; send-pr -a /var/run/dmesg -a /tmp/errors Don't worry about binary files; they will be automatically encoded so as not to upset your mail agent. - + If you attach a patch, make sure you use the or option to &man.diff.1; to create a context or unified diff, and make @@ -218,15 +219,15 @@ FreeBSD Entities//EN"> %freebsd; The template consists of a list of fields, some of which are pre-filled, and some of which have comments explaining - their purpose or listing acceptable values. Don't worry about - the comments; they'll be removed automatically if you don't - modify them or remove them yourself. + their purpose or listing acceptable values. Do not worry + about the comments; they will be removed automatically if you + do not modify them or remove them yourself. At the top of the template, below the SEND-PR: lines, are the email headers. You - don't normally need to modify these, unless you're sending the - PR from a machine or account that can send but not receive - mail, in which case you'll want to set the + do not normally need to modify these, unless you are sending + the problem report from a machine or account that can send but + not receive mail, in which case you will want to set the From: and Reply-To: to your real email address. You may also want to send yourself (or someone else) a carbon copy of the problem report by @@ -258,17 +259,18 @@ FreeBSD Entities//EN"> %freebsd; Confidential: This is prefilled to no; changing it makes no sense as - there is no such thing as a confidential FreeBSD PR - — the PR database is distributed worldwide by + there is no such thing as a confidential FreeBSD problem + report—the PR database is distributed worldwide by CVSup. Synopsis: Fill this out with a short and accurate description of the problem. The - synopsis is used as the subject of the PR email, and is - used in PR listings and summaries; problem reports with - obscure synopses tend to get ignored. + synopsis is used as the subject of the problem report + email, and is used in problem report listings and + summaries; problem reports with obscure synopses tend to + get ignored. If your problem report includes a patch, please have the synopsis start with [PATCH]. @@ -278,12 +280,12 @@ FreeBSD Entities//EN"> %freebsd; Severity: One of non-critical, serious or - critical. Don't overreact; refrain + critical. Do not overreact; refrain from labeling your problem critical unless it really is (e.g. root exploit, easily reproducible panic). Developers tend to ignore this and - the next field, precisely because PR submitters tend to - overrate their problems. + the next field, precisely because problem report + submitters tend to overrate their problems. @@ -291,7 +293,7 @@ FreeBSD Entities//EN"> %freebsd; low, medium or high. See above. - + Category: Choose one of the following: @@ -337,7 +339,7 @@ FreeBSD Entities//EN"> %freebsd; - misc: anything that doesn't fit + misc: anything that does not fit in any of the other categories. @@ -384,13 +386,13 @@ FreeBSD Entities//EN"> %freebsd; - + Release: The version of FreeBSD that you are running. This is filled out automatically by &man.send-pr.1; and need only be changed if you are - sending a PR from a different system than the one that - exhibits the problem. + sending a problem report from a different system than the + one that exhibits the problem. @@ -404,12 +406,12 @@ FreeBSD Entities//EN"> %freebsd; operating system version, the version of the specific program or file that contains the problem, and any other relevant items such as system configuration, other - installed software that influences the problem, etc. - — quite simply everything a developer needs to know - to reconstruct the environment in which the problem + installed software that influences the problem, + etc.—quite simply everything a developer needs to + know to reconstruct the environment in which the problem occurs. - + Description: A complete and accurate description of the problem you are experiencing. @@ -418,30 +420,30 @@ FreeBSD Entities//EN"> %freebsd; it may mislead a developer into making incorrect assumptions about the problem. - + How-To-Repeat: A summary of the actions you need to take to reproduce the problem. - + Fix: Preferably a patch, or at least a workaround (which not only helps other people with the same problem work around it, but may also help a developer understand the cause for the problem), but if - you don't have any firm ideas for either, it's better to + you do not have any firm ideas for either, it's better to leave this field blank than to speculate. - Sending off the PR + Sending off the problem report - Once you're done filling out the template, have saved it, + Once you are done filling out the template, have saved it, and exit your editor, &man.send-pr.1; will prompt you with s)end, e)dit or a)bort?. You can then hit - s to go ahead and submit the PR, + s to go ahead and submit the problem report, e to restart the editor and make further modifications, or a to abort. If you choose the latter, your problem report will remain on @@ -450,9 +452,8 @@ FreeBSD Entities//EN"> %freebsd; transfer it to a system with better net connectivity, before sending it with the to &man.send-pr.1;: - -&prompt.user; send-pr -f ~/my-problem-report - + +&prompt.user; send-pr -f ~/my-problem-report This will read the specified file, validate the contents, strip comments and send it off. @@ -463,27 +464,26 @@ FreeBSD Entities//EN"> %freebsd; Follow-up - Once your problem report has been filed, you'll receive a + Once your problem report has been filed, you will receive a confirmation by email which will include the tracking number - that was assigned to your PR and a URL you can use to check its - status. With a little luck, someone will take an interest in - your problem and try to address it, or, as the case may be, - explain why it's not a problem. You'll be automatically - notified of any change of status, and you'll receive copies of - any comments or patches someone may attach to your PR's audit - trail. + that was assigned to your problem report and a URL you can use + to check its status. With a little luck, someone will take an + interest in your problem and try to address it, or, as the case + may be, explain why it is not a problem. You will be + automatically notified of any change of status, and you will + receive copies of any comments or patches someone may attach to + your problem report's audit trail. If someone requests additional information from you, or you - remember or discover something you didn't mention in the initial - report, just mail it to bug-followup@FreeBSD.org, - making sure that the tracking number is included in the subject - so the bug tracking system will know what problem report to - attach it to. + remember or discover something you did not mention in the + initial report, just mail it to + bug-followup@FreeBSD.org, making sure that the + tracking number is included in the subject so the bug tracking + system will know what problem report to attach it to. If the problem report remains open after the problem has gone away, just send a follow-up (in the manner prescribed - above) saying that the PR can be closed, and, if possible, - explaining how or when the problem was fixed. + above) saying that the problem report can be closed, and, if + possible, explaining how or when the problem was fixed. -