1.4 Feedback ¶

If you find problems with Org, or if you have questions, remarks, or ideas about it, please send an email to the Org mailing list mailto:emacs-orgmode@gnu.org. You can subscribe to the list from this web page. If you are not a member of the mailing list, your mail will be passed to the list after a moderator has approved it². We ask you to read and respect the GNU Kind Communications Guidelines when sending messages on this mailing list. Please allow up to one month for the response and followup if no response is received on the bug report.

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) and Org (M-x org-version), as well as the Org related setup in the Emacs init file. The easiest way to do this is to use the command

M-x org-submit-bug-report <RET>

which puts all this information into an Emacs mail buffer so that you only need to add your description. If you are 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"))

If you are using Org mode version from Git repository, you can start minimal session using make.

# Bare Emacs
make repro
# or pass extra arguments
make repro REPRO_ARGS="-l /path/to/minimal/config.el /tmp/bug.org"

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?

If you experience degraded performance, you can record a “profile” and share it on the Org mailing list. See below for the instructions how to record a useful profile.

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 do not 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, from the menu: Org → Refresh/Reload → Reload Org uncompiled.

2. Then, activate the debugger:

   M-x toggle-debug-on-error <RET>
   

   or, from the menu: Options → Enter Debugger on Error.

3. Do whatever you have to do to hit the error. Do not forget to document the steps you take.
4. When you hit the error, a ‘*Backtrace*’ buffer appears on the screen. Save this buffer to a file—for example using C-x C-w—and attach it to your bug report.

How to profile Org performance ¶

Sometimes, Org is becoming slow for no apparent reason. Such slowdown is often caused by interaction between third-party packages and Org mode. However, identifying the root cause is not always straightforward.

Emacs is able to record performance statistics, which can then be used to find out which functions are taking most of the time to execute. To record the statistics, one can use so-called profiler. To use the Emacs profiler, we recommend the following steps:

1. Make sure that no profiler is currently active:

   M-x profiler-stop <RET>
   

2. Start a new CPU profiler session:

   M-x profiler-start <RET> cpu <RET>
   

3. Use Emacs as usual, performing the actions that are deemed slow.
4. Display and examine the recorded performance statistics:

   M-x profiler-report <RET>
   

   This command will display a summary of the commands and functions that have been executed between profiler-start and profiler-report invocations, with command taking most of the time displayed on top.

   ‘<TAB>’ key can be used to fold and unfold lines in the profiler buffer. The child items revealed upon unfolding are the functions and commands called by the unfolded parent.

   The root causes are often buried deep inside sub-children items in the profiler. You can press ‘B’ (profiler-report-render-reversed-calltree) to quickly reveal the actual function/command that takes most of the time to run.

   Pressing ‘C’ profiler-report-render-calltree will recover the original view.

5. If you need further help, you can share the statistics data.

   Just save the data by issuing

   M-x profiler-report-write-profile <RET>
   /path/to/profile-file-to-be-saved <RET>
   

   Then, you can attached the saved file to your email to the Org mailing list, alongside with details about what you did to trigger the slowdown.

   Note that the saved statistics will only contain the function names and how long their execution takes. No private data will be recorded.