Guidance for Writing Issues

The purpose of this very brief document is to give you some pointers for writing up issues to submit to a project.

  1. Make sure that you read the CONTRIBUTING document for the project, if it exists, to see if the project expects issues to be reported in a specific format or to contain specific information.
  2. Make sure the issue has not been reported already by searching through the issue tracker for terms related to what you are about to report.
  3. Make sure to identify in the title of the issue whether it is
    • a defect (bug) in code:
      This can be manifested by program malfunctioning if source code, or if a document, incorrect information, spelling errors, etc.
    • a design flaw:
      This can be a program that does not malfunction but whose behavior is not the natural or expected behavior. In a document, it is an editorial change, like suggesting different language for a paragraph.
    • feature request:
      There is no malfunctioning, but the program does not do something that you think would be a nice addition. With a document, it is a suggestion to add some ideas or text that improves the flow or supports soe premise, and so on.
  4. Make sure that

    • it is reproducible:
      If the developers cannot reproduce it or conclusively prove that it exists, they probably will not be able to fix it, and move on to the next bug. Provide step-by-step instructions for reproducing the bug for a quicker resolution. Attach or link to videos and screenshots if that would be helpful. For documents, this is not relevant.
    • it is specific:
      Try and figure out exactly what causes the problem. Do not report more than one issue in the same report. You should report each issue separately. For documents, be specific about where in the document the issue is.
    • you describe your environment:
      Include information about the version of the software or document, operating system, and other components on which execution might rely.
    • you write a good title:
      You should be as precise and clear as possible in the title. Titles such as "Program hangs" or "It doesn't work" are not useful.
    • if it is a bug and the issue tracker has bug description fields:
      Make sure you complete the fields.
Valid CSS! Valid HTML 4.01 Transitional