org: Feedback
1.4 Feedback
============
If you find problems with Org, or if you have questions, remarks, or
ideas about it, please mail to the Org mailing list
<emacs-orgmode@gnu.org>. If you are not a member of the mailing list,
your mail will be passed to the list after a moderator has approved
it(1).
For bug reports, please first try to reproduce the bug with the
latest version of Org available—if you are running an outdated version,
it is quite possible that the bug has been fixed already. If the bug
persists, prepare a report and provide as much information as possible,
including the version information of Emacs (‘M-x emacs-version <RET>’)
and Org (‘M-x org-version RET’), as well as the Org related setup in
‘.emacs’. The easiest way to do this is to use the command
M-x org-submit-bug-report RET
which will put all this information into an Emacs mail buffer so that
you only need to add your description. If you re not sending the Email
from within Emacs, please copy and paste the content into your Email
program.
Sometimes you might face a problem due to an error in your Emacs or
Org mode setup. Before reporting a bug, it is very helpful to start
Emacs with minimal customizations and reproduce the problem. Doing so
often helps you determine if the problem is with your customization or
with Org mode itself. You can start a typical minimal session with a
command like the example below.
$ emacs -Q -l /path/to/minimal-org.el
However if you are using Org mode as distributed with Emacs, a
minimal setup is not necessary. In that case it is sufficient to start
Emacs as ‘emacs -Q’. The ‘minimal-org.el’ setup file can have contents
as shown below.
;;; Minimal setup to load latest 'org-mode'
;; activate debugging
(setq debug-on-error t
debug-on-signal nil
debug-on-quit nil)
;; add latest org-mode to load path
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/lisp"))
(add-to-list 'load-path (expand-file-name "/path/to/org-mode/contrib/lisp" t))
If an error occurs, a backtrace can be very useful (see below on how
to create one). Often a small example file helps, along with clear
information about:
1. What exactly did you do?
2. What did you expect to happen?
3. What happened instead?
Thank you for helping to improve this program.
How to create a useful backtrace
................................
If working with Org produces an error with a message you don’t
understand, you may have hit a bug. The best way to report this is by
providing, in addition to what was mentioned above, a _backtrace_. This
is information from the built-in debugger about where and how the error
occurred. Here is how to produce a useful backtrace:
1. Reload uncompiled versions of all Org mode Lisp files. The
backtrace contains much more information if it is produced with
uncompiled code. To do this, use
C-u M-x org-reload RET
or select ‘Org -> Refresh/Reload -> Reload Org uncompiled’ from the
menu.
2. Go to the ‘Options’ menu and select ‘Enter Debugger on Error’
(XEmacs has this option in the ‘Troubleshooting’ sub-menu).
3. Do whatever you have to do to hit the error. Don’t forget to
document the steps you take.
4. When you hit the error, a ‘*Backtrace*’ buffer will appear on the
screen. Save this buffer to a file (for example using ‘C-x C-w’)
and attach it to your bug report.
---------- Footnotes ----------
(1) Please consider subscribing to the mailing list, in order to
minimize the work the mailing list moderators have to do.
Info Catalog
org: Activation
org: Introduction
org: Conventions