[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Emacs-diffs] /srv/bzr/emacs/emacs-23 r100033: Various updates for the B
From: |
Glenn Morris |
Subject: |
[Emacs-diffs] /srv/bzr/emacs/emacs-23 r100033: Various updates for the Bugs section of the manual. |
Date: |
Sat, 11 Sep 2010 17:31:47 -0700 |
User-agent: |
Bazaar (2.0.3) |
------------------------------------------------------------
revno: 100033
committer: Glenn Morris <address@hidden>
branch nick: emacs-23
timestamp: Sat 2010-09-11 17:31:47 -0700
message:
Various updates for the Bugs section of the manual.
* doc/emacs/trouble.texi (Bugs): Update the section intro.
(Known Problems): New section.
(Checklist): Misc updates. Prefer M-x report-emacs-bug.
(Sending Patches): Bug fixes are best as responses to existing bugs.
* doc/emacs/emacs.texi (Known Problems): Add menu entry for new section.
modified:
doc/emacs/ChangeLog
doc/emacs/emacs.texi
doc/emacs/trouble.texi
=== modified file 'doc/emacs/ChangeLog'
--- a/doc/emacs/ChangeLog 2010-09-04 18:58:56 +0000
+++ b/doc/emacs/ChangeLog 2010-09-12 00:31:47 +0000
@@ -1,3 +1,11 @@
+2010-09-12 Glenn Morris <address@hidden>
+
+ * trouble.texi (Bugs): Update the section intro.
+ (Known Problems): New section.
+ (Checklist): Misc updates. Prefer M-x report-emacs-bug.
+ (Sending Patches): Bug fixes are best as responses to existing bugs.
+ * emacs.texi (Known Problems): Add menu entry for new section.
+
2010-09-04 Chong Yidong <address@hidden>
* dired.texi (Dired Enter): Minor doc fix (Bug#6982).
=== modified file 'doc/emacs/emacs.texi'
--- a/doc/emacs/emacs.texi 2010-06-23 02:46:43 +0000
+++ b/doc/emacs/emacs.texi 2010-09-12 00:31:47 +0000
@@ -1135,6 +1135,7 @@
Reporting Bugs
+* Known Problems:: How to read about known problems and bugs.
* Bug Criteria:: Have you really found a bug?
* Understanding Bug Reporting:: How to report a bug effectively.
* Checklist:: Steps to follow for a good bug report.
=== modified file 'doc/emacs/trouble.texi'
--- a/doc/emacs/trouble.texi 2010-06-23 02:46:43 +0000
+++ b/doc/emacs/trouble.texi 2010-09-12 00:31:47 +0000
@@ -409,29 +409,76 @@
@section Reporting Bugs
@cindex bugs
- Sometimes you will encounter a bug in Emacs. Although we cannot
-promise we can or will fix the bug, and we might not even agree that it
-is a bug, we want to hear about problems you encounter. Often we agree
-they are bugs and want to fix them.
-
- To make it possible for us to fix a bug, you must report it. In order
-to do so effectively, you must know when and how to do it.
-
- Before reporting a bug, it is a good idea to see if it is already
-known. You can find the list of known problems in the file
address@hidden/PROBLEMS} in the Emacs distribution; type @kbd{C-h C-p} to read
-it. Some additional user-level problems can be found in @ref{Bugs and
-problems, , Bugs and problems, efaq, GNU Emacs FAQ}. Looking up your
-problem in these two documents might provide you with a solution or a
-work-around, or give you additional information about related issues.
+ If you think you have found a bug in Emacs, please report it. We
+cannot promise to fix it, or always to agree that it is a bug, but we
+certainly want to hear about it. The same applies for new features
+you would like to see added. The following sections will help you to
+construct an effective bug report.
@menu
+* Known Problems:: How to read about known problems and bugs.
* Criteria: Bug Criteria. Have you really found a bug?
* Understanding Bug Reporting:: How to report a bug effectively.
* Checklist:: Steps to follow for a good bug report.
* Sending Patches:: How to send a patch for GNU Emacs.
@end menu
address@hidden Known Problems
address@hidden Reading Existing Bug Reports and Known Problems
+
+ Before reporting a bug, if at all possible please check to see if it
+is already known about. Indeed, it may already have been fixed in a
+later release of Emacs, or in the development version. Here is a list
+of the main places you can read about known issues:
+
address@hidden
address@hidden
+The @file{etc/PROBLEMS} file in the Emacs distribution; type @kbd{C-h
+C-p} to read it. This file contains a list of particularly well-known
+issues that have been encountered in compiling, installing and running
+Emacs. Often, there are suggestions for workarounds and solutions.
+
address@hidden
+Some additional user-level problems can be found in @ref{Bugs and
+problems, , Bugs and problems, efaq, GNU Emacs FAQ}.
+
address@hidden
+The @samp{bug-gnu-emacs} mailing list (also available as the newsgroup
address@hidden). This is where you will find most Emacs bug
+reports. You can read the list archives at
address@hidden://lists.gnu.org/mailman/listinfo/bug-gnu-emacs}. If you
+like, you can also subscribe to the list. Be aware that the sole
+purpose of this list is to provide the Emacs maintainers with
+information about bugs and feature requests. Reports may contain
+fairly large amounts of data; spectators should not complain about
+this.
+
address@hidden
+The bug tracker at @url{http://debbugs.gnu.org}. From early 2008,
+reports from the @samp{bug-gnu-emacs} list have been sent here. The
+tracker contains the same information as the mailing list, just in a
+different format. You may prefer to browse and read reports using the
+tracker.
+
address@hidden
+The @samp{emacs-pretest-bug} mailing list. This list is no longer
+used, and is mainly of historical interest. At one time, it was used
+for bug reports in development (i.e., not yet released) versions of
+Emacs. You can read the archives for 2003 to mid 2007 at
address@hidden://lists.gnu.org/archive/html/emacs-pretest-bug/}. From
+late 2007 to mid 2008, the address was an alias for the
address@hidden mailing list. From mid 2008 onwards, it has been
+an alias for @samp{bug-gnu-emacs}.
+
address@hidden
+The @samp{emacs-devel} mailing list. Sometimes people report bugs to
+this mailing list. This is not the main purpose of the list, however,
+and it is much better to send bug reports to the bug list. You should
+not feel obliged to read this list before reporting a bug.
+
address@hidden itemize
+
+
@node Bug Criteria
@subsection When Is There a Bug
@@ -540,56 +587,81 @@
@subsection Checklist for Bug Reports
@cindex reporting bugs
- The best way to send a bug report is to mail it electronically to the
-Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}. (If you want to
-suggest a change as an improvement, use the same address.)
-
- If you'd like to read the bug reports, you can find them on the
-newsgroup @samp{gnu.emacs.bug}; keep in mind, however, that as a
-spectator you should not criticize anything about what you see there.
-The purpose of bug reports is to give information to the Emacs
-maintainers. Spectators are welcome only as long as they do not
-interfere with this. In particular, some bug reports contain fairly
-large amounts of data; spectators should not complain about this.
-
- Please do not post bug reports using netnews; mail is more reliable
-than netnews about reporting your correct address, which we may need
-in order to ask you for more information. If your data is more than
-500,000 bytes, please don't include it directly in the bug report;
-instead, offer to send it on request, or make it available by ftp and
-say where.
+
+ Before reporting a bug, first try to see if the problem has already
+been reported (@pxref{Known Problems}).
+
+If you are able to, try the latest release of Emacs to see if the
+problem has already been fixed. Even better is to try the latest
+development version. We recognize that this is not easy for some
+people, so do not feel that you absolutely must do this before making
+a report.
@findex report-emacs-bug
- A convenient way to send a bug report for Emacs is to use the command
address@hidden report-emacs-bug}. This sets up a mail buffer (@pxref{Sending
-Mail}) and automatically inserts @emph{some} of the essential
-information. However, it cannot supply all the necessary information;
-you should still read and follow the guidelines below, so you can enter
-the other crucial information by hand before you send the message.
+ The best way to write a bug report for Emacs is to use the command
address@hidden report-emacs-bug}. This sets up a mail buffer
+(@pxref{Sending Mail}) and automatically inserts @emph{some} of the
+essential information. However, it cannot supply all the necessary
+information; you should still read and follow the guidelines below, so
+you can enter the other crucial information by hand before you send
+the message. You may feel that some of the information inserted by
address@hidden report-emacs-bug} is not relevant, but unless you are
+absolutely sure it is best to leave it, so that the developers can
+decide for themselves.
+
+When you have finished writing your report, type @kbd{C-c C-c} and it
+will be sent to the Emacs maintainers at @email{bug-gnu-emacs@@gnu.org}.
+(If you want to suggest an improvement or new feature, use the same
+address.) If you cannot send mail from inside Emacs, you can copy the
+text of your report to your normal mail client and send it to that
+address. Or you can simply send an email to that address describing
+the problem.
+
+Your report will be sent to the @samp{bug-gnu-emacs} mailing list, and
+stored in the tracker at @url{http://debbugs.gnu.org}. Please try to
+include a valid reply email address, in case we need to ask you for
+more information about your report. Submissions are moderated, so
+there may be a delay before your report appears.
+
+You do not need to know how the @url{http://debbugs.gnu.org} bug
+tracker works in order to report a bug, but if you want to, you can
+read the tracker's online documentation to see the various features
+you can use.
+
+All mail sent to the @samp{bug-gnu-emacs} mailing list is also
+gatewayed to the @samp{bug.gnu.emacs} newsgroup. The reverse is also
+true, but we ask you not to post bug reports via the newsgroup. It
+can make it much harder to contact you if we need to ask for more
+information, and it does not integrate well with the bug tracker.
+
+If your data is more than 500,000 bytes, please don't include it
+directly in the bug report; instead, offer to send it on request, or
+make it available by ftp and say where.
To enable maintainers to investigate a bug, your report
should include all these things:
@itemize @bullet
@item
-The version number of Emacs. Without this, we won't know whether there
-is any point in looking for the bug in the current version of GNU
-Emacs.
+The version number of Emacs. Without this, we won't know whether there is any
+point in looking for the bug in the current version of GNU Emacs.
-You can get the version number by typing @kbd{M-x emacs-version
address@hidden If that command does not work, you probably have something
-other than GNU Emacs, so you will have to report the bug somewhere
-else.
address@hidden report-emacs-bug} includes this information automatically,
+but if you are not using that command for your report you can get the
+version number by typing @kbd{M-x emacs-version @key{RET}}. If that
+command does not work, you probably have something other than GNU
+Emacs, so you will have to report the bug somewhere else.
@item
The type of machine you are using, and the operating system name and
-version number. @kbd{M-x emacs-version @key{RET}} provides this
-information too. Copy its output from the @samp{*Messages*} buffer, so
-that you get it all and get it accurately.
+version number (again, automatically included by @kbd{M-x
+report-emacs-bug}). @kbd{M-x emacs-version @key{RET}} provides this
+information too. Copy its output from the @samp{*Messages*} buffer,
+so that you get it all and get it accurately.
@item
The operands given to the @code{configure} command when Emacs was
-installed.
+installed (automatically included by @kbd{M-x report-emacs-bug}).
@item
A complete list of any modifications you have made to the Emacs source.
@@ -619,12 +691,15 @@
@item
The precise commands we need to type to reproduce the bug.
+If at all possible, give a full recipe for an Emacs started with the
address@hidden option (@pxref{Initial Options}). This bypasses your
address@hidden customizations.
@findex open-dribble-file
@cindex dribble file
@cindex logging keystrokes
-The easy way to record the input to Emacs precisely is to write a
-dribble file. To start the file, execute the Lisp expression
+One way to record the input to Emacs precisely is to write a dribble
+file. To start the file, execute the Lisp expression
@example
(open-dribble-file "~/dribble")
@@ -735,7 +810,7 @@
including your @file{.emacs} file, set any variables that may affect the
functioning of Emacs. Also, see whether the problem happens in a
freshly started Emacs without loading your @file{.emacs} file (start
-Emacs with the @code{-q} switch to prevent loading the init file). If
+Emacs with the @code{-Q} switch to prevent loading the init files). If
the problem does @emph{not} occur then, you must report the precise
contents of any programs that you must load into the Lisp world in order
to cause the problem to occur.
@@ -907,12 +982,10 @@
@itemize @bullet
@item
Send an explanation with your changes of what problem they fix or what
-improvement they bring about. For a bug fix, just include a copy of the
-bug report, and explain why the change fixes the bug.
-
-(Referring to a bug report is not as good as including it, because then
-we will have to look it up, and we have probably already deleted it if
-we've already fixed the bug.)
+improvement they bring about. For a fix for an existing bug, it is
+best to reply to the relevant discussion on the @samp{bug-gnu-emacs}
+list, or item in the @url{http://debbugs.gnu.org} tracker. Explain
+why your change fixes the bug.
@item
Always include a proper bug report for the problem you think you have
[Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Emacs-diffs] /srv/bzr/emacs/emacs-23 r100033: Various updates for the Bugs section of the manual.,
Glenn Morris <=