Reporting Problems

Problems? Problems? Impossible!

Well, maybe not... We'd like to hear what you've uncovered but it's in your best interests to do some initial research.

First, you need to verify that your potential problem hasn't already been reported by reading the Cygwin FAQ and the mailing list archives. If your issue is still unresolved, feel free to write to the cygwin list with your problem.

Before you start asking questions please take a moment to read and understand some very good general advice on how to ask smart questions. Once you've followed that link and read the advice, please demonstrate that you've actually gained some smartness by not sending your Cygwin question to the authors at the link. That would be a really stupid thing to do.

For Cygwin advice please come back here.

It is not always easy to figure out when you have a user problem and when you've found a valid Cygwin bug. If you have tracked things down as far as verifying to yourself that you've found a bug, please consider investigating it yourself and sending us patches if you figure out a solution. Bug reports without solutions are also ok, of course, although if you really want a bug fixed you can exercise the power implicit in free software and provide the patch yourself.

Otherwise, if you can't determine if you've discovered a bug or just are having problems that require help, send a detailed description (with a test case if possible) to the appropriate mailing list after reading all of problem reporting guidelines on this page. Due to the mailing list volume, we don't always reply to individual reports sent to the list but we do keep track of them.

Shouldn't I just send email to straight to a Cygwin developer or package maintainer?

Using the correct Cygwin mailing list is absolutely the proper way to report problems or make observations. The mailing lists were created for this express purpose. Reporting problems to a public forum means that the workload is shared and, since your report will be read by many people, it may get more attention than one person would be able to provide.

So, there is generally no need to "Cc" a package maintainer with your observations. All maintainers should be reading the appropriate mailing list so Ccing them will result in sending them two copies of your email.

This is particularly true if you notice that someone has specifically set the Reply-To of a message to go only to the cygwin mailing list. Some contributors even take this a step further and actually set their return address to the mailing list in an attempt to make it very obvious that Cygwin-related email should go to the mailing list.

Nevertheless, some people still seem to insist on either Cc'ing Cygwin contributors or sending private email. This is inconsiderate. Please do not do this unless specifically requested.

Reporting guidelines

• Use a subject line that describes the issue well:
  
  Good examples:
  

  "1.7.10: possible Cygwin DLL select bug (W7 and XP)"
  "problem with open() in perl 5.14.1-2"
  "question about cat'ing binary files in bash"

  Bad examples:
  

  "question?"
  "bug"
  "porting problem"
  "help!!!!"
  "bash question"
  "newbie needs help"
  "Question for Jane Simmons"
  "make"
  "gcc"
  "grep"
  (basically any single word subject)

  This also applies to general non-problem-related discussion. It's very hard to follow the list when most of the subject lines look very similar.
• When reporting problems, describe the problem rather than just including your interpretation of the problem.
  
  Bad example:
  

  "Cygwin's setup fails to operate when the humidity is high. How can I solve Cygwin's problem with high humidity?"

  Good example:
  

  "I'm noticing this summer, that whenever I try to install Cygwin, setup dies with a fatal exception at NNNNNN. Could this be a problem with humidity?"

• Run cygcheck -s -v -r > cygcheck.out and include that file as an attachment in your report. Please do not compress or otherwise encode the output. Just attach it as a straight text file so that it can be easily viewed.
  
  Note: It is ok to redact sensitive information like username and to remove site-specific environment variables but please note that fact in your email message so that we'll know that the cygcheck output has been modified.
• Similarly, if your problem involves the Cygwin/X server, include the file /var/log/xwin/XWin.0.log in addition to your cygcheck output as plain-text attachments in your report.
• Do not assume that your problem is so trivial or so "well known" that it does not require any details or background from you. Many (most?) people who report problems fall into the trap of assuming that people are "clued into" their mental state when, in most cases, this is not the case.
  
  As a rule of thumb, if you find yourself referring to your problem as the problem with XYZ rather than a problem with XYZ then your message is suspect. Using the in this context means that you are assuming that your problem is well known. Unless you can point to an email message thread or FAQ entry (either of which is a good idea, btw) please do not assume that the readers of your message will be familiar with your problem.
• If you are experiencing problems with a package which is not part of the Cygwin distribution first see if there is a better forum available for discussing it. Don't expect that just because you are having problems with a package on Cygwin that there is a problem with Cygwin. If you truly think that this is a generic problem with Cygwin, then explain what the package is and where it came from rather than expecting people to "just know".
• Try to confine your email to one problem per message. Do not reuse previous subjects to report unrelated problems.
• Reply to the email in the thread that you started rather than creating a new message for each reply. If you just send a new message every time you want to offer something about your problem, you will confuse people who want to help but are expecting the discussion to occur in the thread that you created.
• In your (detailed) description, show how to reproduce the problem. This means including a test case if at all possible.
• If you can't run cygcheck for some reason (and why shouldn't you be able to? cygcheck is just a standard windows program which does not use the Cygwin dll), at the very least, explain why you can't use cygcheck, include the Cygwin release you are using, and give the operating system and its version number: e.g. "Cygwin v1.7.8 under Windows 7".
• Avoid the use of exclamation marks or multiple question marks. They add nothing to the report and provide the impression that you are too excited to think calmly about the problem.
• Avoid personal details about why you need the problem rectified, how important it is for you to have it fixed, or how long you've worked on it. People will be more likely to look at your email if it is cut and dry, to the point, and uses a minimum of extra words.
• Avoid expressions of incredulity like "I can't believe that this is so broken!" or other editorializing.
• Minimize reporting that your problem "works fine" on some "other" UNIX platform or used to work ok in a previous Cygwin release. This is marginally useful data but it does not guarantee that you've uncovered a Cygwin problem. Cygwin can change its behavior between releases; sometimes to fix an operational problem and sometimes, well... because we've introduced a bug.
  
  With regard to differing behavior from some flavor of UNIX: UNIXes vary in their behavior and Cygwin is basically a different flavor of UNIX. One common source of differing behavior is with programs which rely on specific malloc behavior, like being able to free a pointer twice or being able to access memory after freeing. Cygwin is unforgiving about this kind of practice while some older linux versions of malloc are not.
  
  Many people seem to latch onto the fact that their issues do not seem to occur in other versions of UNIX or Cygwin and mention this in all followup email when people attempt to help them with the problem. However, this information is usually only useful in the first message and does not usually bear repeating.
• Keep in mind that there are thousands of people on the mailing list. Try to avoid "me too" responses or reporting problems that have already been reported. It's hard enough keeping up with the volume as it is...
• Send a patch to fix the problem if you can.