Skip to content

SubmittingBugs

Jump to bottom
Jeff Squyres edited this page Sep 18, 2018 · 24 revisions

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 against release branches in the ompi 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

Submit a bug or enhancement request via Github Issues in the ompi repository. Submissions require two general steps:

  1. Submit the title and body.

  2. Assign labels, a milestone, and a developer.

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

  1. 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
  2. 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
  3. Set the target branch(es) to which the issue is relevant. It is common to select more than one branch (e.g., if the branch exists in both master and one or more release branches).
    • Target: master: This bug affects master
    • Target: v2.0.x: This bug affects v2.0.x
    • Target: v2.x: This bug affects v2.x
    • Target: v3.0.x: This bug affects v3.0.x
    • ...and so on
    • These labels are important because Github only allows us to select one milestone -- even if an issue affects more than one branch (because Open MPI's milestones pretty much correspond directly to release branches).
  4. Set the state of this issue
    • State: Awaiting code: This issue has no PR / code fix submitted yet.
    • State: Awaiting developer information: Waiting for an Open MPI community developer to provide information (e.g., in a comment on this PR).
    • State: Awaiting user information: Waiting for a user (potentially the submitter) to provide information (e.g., in a comment on this PR).
    • State: Awaiting merge to release branches: The PR has been merged to master, but this issue is still open because corresponding PRs need to be opened and/or merged to relevant release branches (see the Target: labels).
    • State: PR posted: A PR for this issue has been posted (likely to master), but has not been merged yet.
    • State: Verification of fix: The issue has nominally been fixed; we're awaiting final confirmation that the fix is correct / verified.
    • State: wontfix: It has been decided that this issue will not be fixed.

Note that developers will need to manually update 'State:' labels when they reply on open issues. This is a necessary evil; sorry. The benefits outweigh the costs here -- the 'State:' labels helps us manage large numbers of issues over time.

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.
Clone this wiki locally