How do I submit a detailed bug report?

Note: only do this if you have been explicitly asked to do so.

Scenario:

You posted a question about a problem you had with GATK tools, we answered that we think it's a bug, and we asked you to submit a detailed bug report.

Here's what you need to provide:

• The exact command line that you used when you had the problem (in a text file)
• The full log output (program output in the console) from the start of the run to the end or error message (in a text file)
• A snippet of the BAM file if applicable and the index (.bai) file associated with it
• If a non-standard reference (i.e. not available in our resource bundle) was used, we need the .fasta, .fai, and .dict files for the reference
• Any other relevant files such as recalibration plots

A snippet file is a slice of the original BAM file which contains the problematic region and is sufficient to reproduce the error. We need it in order to reproduce the problem on our end, which is the first necessary step to finding and fixing the bug. We ask you to provide this as a snippet rather than the full file so that you don't have to upload (and we don't have to process) huge giga-scale files.

Here's how you create a snippet file:

• Look at the error message and see if it cites a specific position where the error occurred
• If not, identify what region caused the problem by running with -L argument and progressively narrowing down the interval
• Once you have the region, use PrintReads with -L to write the problematic region (with 500 bp padding on either side) to a new file -- this is your snippet file.
• Test your command line on this snippet file to make sure you can still reproduce the error on it.

And finally, here's how you send us the files:

• Put all those files into a .zip or .tar.gz archive

• Upload them onto our FTP server with the following credentials:

  location: ftp.broadinstitute.org
  username: gsapubftp
  password: 5WvQWSfi
  

• Post in the original discussion thread that you have done this

• Be sure to tell us the name of your archive file!

We will get back to you --hopefully with a bug fix!-- as soon as we can.