Reporting bugs in Demeter

All software has bugs. This software certainly has bugs. This document explains how to report problems with the software effectively. In this context “effectively” means in a manner such that I am likely to understand the problem and, therefore, likely to fix it promptly.

The 2 rules of good bug reporting

  1. Use the Ifeffit mailing list. The mailing list is always an appropriate place to report problems with the software. You can also use DEMETER's issue tracker at GitHub.
  2. Provide enough information that your problem can be reproduced by someone else. That may mean providing the data or project file that triggers the problem. That may mean explaining step-by-step how to arrive at the problem. That may mean taking a screenshot to demonstrate the appearance of the problem. In any case, be explicit, be concise, and be precise.

Caution

If a problem cannot be reproduced on my computer, I cannot possibly solve it.

There are good reasons to use the mailing list:

  • I read and respond to questions on the mailing list. So do many other people, any whom may be able to help you with your problem.
  • The problem and – hopefully – its solution will be archived. That means that someone else having the same problem might find that solution.

The corollaries to those two rules are

  1. Don't send email directly to me.
  2. Don't be vague.

If you send mail directly to me, the likely response will be a polite request to use the mailing list. If you are vague, the likely response will be to ask you for more information. If you send vague mail directly to me, you may be ignored outright.

For another take on how and why to submit a good bug report, check this out. (Please note that Christensen is not associated in any way with DEMETER or IFEFFIT nor should he be contacted with questions about DEMETER or IFEFFIT.)

Capturing error messages

When DEMETER runs into a problem, it usually emits error messages that are useful for understanding the cause of the bug. Even when ATHENA or ARTEMIS crashes hard, some useful information is usually provided.

A good bug report will include this information. Don't edit this information, regardless of how cryptic or repetitive it may seem.

Windows

Each of the GUI programs (ATHENA, ARTEMIS, and HEPHAESTUS) writes its output messages to a log file. This log file is in the %APPDATA%\demeter folder. On Windows 7, %APPDATA% is typically

C:\Users\<username>\AppData\Roaming\

where <username> is your login name. For me, this ends up being C:\Users\bravel\AppData\Roaming\. On Windows XP and Vista, %APPDATA% is typically

C:\Documents and Settings\<username>\Application Data\

This folder may normally be hidden from view.

Each program writes its own log file. ATHENA's log file is %APPDATA%\demeter\dathena.log and so on.

This log file should be included in any bug report.

Please note that this log file is overwritten every time you fire up the associated program. When reporting a bug, be sure to use the log file you find immediately after encountering your problem and before you relaunch the program.

Linux or other Unix systems

On Linux and other Unixes, the GUI programs do not record log files as described above. Top capture the error message, you should start the program from the command line. ATHENA is started by typing the command dathena, ARTEMIS by typing dartemis and so on. When the bug is encountered, the error messages will be written to the screen. These can be copied and pasted into an email message.

Alternatively, you can use the tee program to record the error messages. Here is an example:

dathena | tee screen_messages.txt

The file screen_messages.txt can then be appended to an email message.

The DOs of reporting bugs

  • DO try downloading the latest version of the software. Your problem may already be solved.
  • DO subscribe to the Ifeffit mailing list and DO try asking your question there. Your problem may have been discussed there or it may be of interest to other users.
  • DO say which program and which version number you are using.
  • DO say what operating system you are using.
  • DO provide the crystallographic data and a literature reference to the crystallographic data when reporting a problem with ATOMS.
  • DO explain clearly and concisely how to replicate the problem.
  • DO send a project file that demonstrates a problem with ATHENA, or ARTEMIS. For a problem with ATHENA, you may also need to send raw data.
  • DO send a screenshot of the program in action if that helps explain the problem. PNG is usually the best choice for a screenshot. GIF is good also. JPG and PDF are ok. TIF sucks. Attach this image file to your mail message directly and DON'T embed it in a Word or PowerPoint file before attaching it. Really, DON'T send me a Word or PowerPoint file that consists of a single image. I frickin' hate that.
  • DO send any output files that help explain the problem. Bugs reports about ATOMS almost always require the faulty feff.inp file.
  • DO use compressed archives if you must send large numbers of files. .zip, .tar.gz, or .tar.bz2 are all acceptable formats for compressed archiving.
  • DO send a follow-up email if a lot of time has passed without a response. I may be on travel or may have set your prior email aside and forgotten to return to it (which would explain but not justify a period of silence). I take bug reports very seriously, but sometimes I needs a reminder.

The DON'Ts of reporting bugs

  • DON'T ask questions about compiling FEFF8 or FEFF9. The only version of FEFF that I support at that level is the version of FEFF6 that comes with IFEFFIT. For questions about FEFF8 or FEFF9, contact someone from the FEFF project.
  • DON'T send any information in the form of a Word or PowerPoint document. It is exceedingly rare that the information conveyed in a bug report requires formatting capabilities that exist in a word processor and that don't exist in plain text email. RTF, LibreOffice, and the like are not an improvement on Word for the purpose of reporting a bug. Indeed, there are situations where using a word processor makes it harder for me to troubleshoot the problem. For example, if I ask you to cut and paste some text displayed by one of the programs, a word processor will change where lines are broken in a way that is confusing for me. On Windows, use NotePad rather than Word for such things.
  • DON'T assume that others use the same email program as you. Specifically DON'T rely upon colored text or fonts in the email message to convey information – your email may not display the same for me as it does for you.
  • DON'T send large files (other than the suggestions above) that have not been requested. If a large file is needed to understand the problem, you will be asked for it in a follow-up email.
  • DON'T ever send anything by fax. DON'T ever send anything by normal post or overnight express. It is the 21st century, after all!
  • DON'T send every file from a FEFF run! It is usually sufficient to send just the feff.inp file. If other files are needed from the FEFF run, you will be asked for them in a follow-up email.


DEMETER is copyright © 2009-2016 Bruce Ravel – This document is copyright © 2016 Bruce Ravel

This document is licensed under The Creative Commons Attribution-ShareAlike License.

If DEMETER and this document are useful to you, please consider supporting The Creative Commons.