SubmittingBugs

In the Open MPI project, we track three main things:

1. Bugs and enhancement requests: These tracked in the Github Issues tracker in the ompi repository.
2. Requests to get code into the release branches: These are tracked in the Pull Requests in the ompi-release repository.
3. RFCs (i.e., "hey, I've got an idea -- what do people think about this?"): These are typically tracked in the Pull Requests in the ompi repository.

You must have a Github account to submit bugs or pull requests.

Submitting a Bug/Enhancement Request

Submitting a bug or enhancement requires two general steps:

1. Submit the title and body.
2. Assign labels, a milestone, and a developer.

Submit the title and body

Title

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.

Body

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!)

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.

Assign labels, milestone, and developer

Once you have submitted the initial issue, we ask that you do a few more things:

1. Assign appropriate labels
2. Assign an appropriate milestone
3. (Optional) Assign the issue to a developer

Assign appropriate labels

Assigning labels are important. If you don't assign appropriate labels, we may not see your issue. You need to assign a label to indicate the type of bug, and optionally assign a label to indicate the severity of the issue:

1. 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

1. 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

Assign a milestone

It is also quite important to assign a milestone to your issue. We might not see your ticket if it has no milestone (or the wrong milestone) attached to it.

The milestone is 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.

Assign to a developer (optional)

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

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

• Always assign labels and a milestone.
• 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.