Skip to content
Jeff Squyres edited this page Sep 10, 2014 · 24 revisions

Submitting Bugs and Enhancements

You must have a Github account to submit bugs.

If this is a code contribution / pull request, then you should file a pull request, not a normal Github issue.

Choose labels

When initially filing a Github issue, assign a label to indicate the type of bug, and optionally assign a label to indicate the severity of the issue:

  • Pick one of these three labels to identify the type of issue:
    • Enhancement: a request for a new feature
    • Bug: a bug
    • Documentation: fix something in Open MPI's documentation
  • Pick one of these labels to assign the severity level of the bug:
    • Blocker: this issue must be fixed ASAP
    • Critical: this issue must be fixed before the next release
    • [no label at all]: this is a "normal" severity issue
    • Minor: this issue is minor/cosmetic, and should be fixed at some point, but there's no rush

Title / body

Fill in a good title for the issue. This should be a one-sentence/phrase concisely describing the issue you are reporting, such that if someone looks at it with zero other context, it should be at least reasonably clear as to what the ticket is about.

NEVER leave a title blank.

Also fill in a good full description for the bug. *Include as much information as possible! * No developer has ever said, "Wow, this guy included too much information on the ticket." Remember that we are not sitting there at your console to see the problem and therefore have no context other than what you include on the bug. So include information. Lots of it. For example, be sure to include at least the following:

  • Use Github Markdown wiki syntax.
  • What version of Open MPI you are using (e.g., a release version, or a Git branch and tag or hash). If this problem spans more than one version, include all versions that you are aware of where the problem occurs (or, conversely, state that you have not tested / do not know if the problem occurs in other versions, etc.).
  • What architecture and compiler you are using?
  • Describe what the problem is -- include all relevant outputs and supplemental information. Be over-obvious. Supply lots of detail. Remember: We are not sitting there next to you, and we have no idea what the setup is where you are trying to run.
  • If you have any suggested fixes, describe those as well (perhaps even attaching a patch!)

After you submit the issue

While it is optional, it is helpful to assign the Milestone: the first version where this defect/enhancement will be fixed/created. By definition, it is impossible to apply fixes/new functionality to versions that have already been released.

Also, if you know who to assign this bug to, go ahead and do so. Otherwise, it's ok to not assign it to anyone.

How do I add attachments?

Attachments are very helpful -- you can supply code snipits, patches, short programs that reproduce the issue, etc.

Unfortunately, Github issues only support picture attachments. If you have a picture attachment, just drag it into the web interface and Github will do the Right Thing.

For all other attachments, if they're too long to paste into the bug itself, then please post them elsewhere (e.g., Github's Gist service is a good choice) and then link to them in the body or a comment of the ticket.

Who gets notified?

E-mails are sent out for most changes to the ticket (e.g., if you add a comment):

  • The person who files the bug
  • Whoever is subscribed to the overall OMPI Github repository
  • Whoever is "watching" this individual ticket (if you comment on a ticket, Github will automatically set you to "watch" that ticket)
  • Whoever the ticket is assigned to

Some best practices

  • Please please please read Github Markdown wiki syntax to see how to format text.
  • Do not cut-n-paste raw code or shell prompts in bugs unless you escape them properly in Github Markdown (i.e., encased in triple-left-single-quotes).
  • Once a defect is fixed or the enhancement is created, close the ticket.
Clone this wiki locally