How to file an MPI Forum issue ("ticket") - mpi-forum/mpi-issues GitHub Wiki

NOTE: This wiki page describes the general procedure and progression of an MPI issue through GitHub. It does not contain example Git commands to effect this procedure (go back to the main wiki page for links to pages that should example Git commands for pull requests).

The usual workflow of an issue (formerly a "ticket") in the MPI Forum is to be discussed first in a working group and then presented to the full forum for consideration. Similarly, when creating an issue in the MPI Forum repository, issues should usually come first through a working group. There are times where a minor ticket can be proposed by an individual for simplicity, but generally it is a good idea to have the working groups vet ideas first.

Working groups have their own Github organizations and repositories which are forked from the main source code repository (e.g., forked from mpi-forum/mpi-standard). To request access to these repositories in order to write a text change, contact the chair of the appropriate working group.

If a repository isn't yet set up, contact Wesley Bland (@wesbland) or Jeff Squyres (@jsquyres) to help set things up.

Overview

The following picture is an overview of how repositories are typically forked and pull requests are filed, using the Tools working group and @jdinan as an example:

Overview of working group issue workflow

Remember that both an issue and a corresponding pull request should be filed, and they should reference each other (e.g., the issue can be automatically closed when the pull request is merged).

Overview of MPI Forum usage

Details

When an issue is ready to be presented to the full Forum, a representative of the working group should begin the process of presenting the issue according to the guidelines below:

Open an issue

  1. Open an issue describing the errata, enhancement, or proposal in detail including background motivation and impact on implementations.
    • Ensure to pick an appropriate label
    • Ensure to pick a meeting milestone
  2. Note the number that Github assigned to the issue

Open a corresponding pull request

  1. Push a branch to the working group repository (or private user's repository if presenting an issue without using a working group).
    • Use the working group repository as a sandbox to make any changes or corrections before presenting the pull request to the Forum as a whole.
  2. Open a pull request to merge the branch from the repository which contains the new branch to the appropriate branch in the appropriate repository (e.g., mpi-forum/-mpi-standard).
    • Note that there are separate branches for each major version of each MPI Forum document (e.g., MPI Standard). The pull request must target the appropriate version for the issue. Guidance on this can be found in the Branch Management wiki page.
    • Opening a pull request can be accomplished by:
      • Navigating to the branch in the private or working group repository and clicking Create Pull Request.
      • The base fork box should indicate the mpi-standard repository and the base box should indicated the desired branch (e.g., mpi-3.x for MPI-3 based tickets).
      • The head fork box should indicate the repository containing the new branch and the compare box should indicated the desired branch.
    • The title and description of the pull request can be a shortened version of the description as it will largely duplicate the text in the issue itself.
    • There is no requirement for reducing the number of commits in a branch to one (via squashing). Branches can either have multiple commits or be squashed in whatever way makes sense for each pull request.
      • An interactive git rebase can be used to squash down to fewer commits when necessary. This helps to simplify the review process if the branch has lots of commits.
      • Remember that the MPI Forum no longer uses LaTeX markup within the official document itself, which means that pull requests should not include change macros. It might be helpful to include this markup in internal versions of the document to assist reading, but it must be removed in the official pull request.
  3. In the last commit of the pull request, include the text Closes mpi-forum/mpi-issues#<issue-number>. This does two things:
    • Allows Github to link the pull request from the issue.
    • Allows Github to automatically close the issue if/when the pull request is merged.

Progression of the issue / pull request

  1. General comments should be made on the public issue. The idea is to be open and allow the public to make comments.
  2. The private pull request, however, must be reviewed by at least one member of each chapter committee from the chapters which the pull request changes.
    • The reviewers should check the pull request for a correct implementation of the ticket, not the validity of the ticket itself. This review is to ensure the correctness of the patch. Please do not abuse the review process to assert editorial control.
    • Pull request reviews must be completed after the issue's reading and before the two week deadline for the first vote.
    • Reviewers can indicate their approval on the pull request by adding comments (e.g., using the "thumbs up" or "thumbs down" emoticons, :+1: or :-1:, which are :+1: and :-1:, respectively).
    • Reviewers can make comments directly on the (private) pull request, but should limit themselves to editorial comments only (i.e., to make the pull request correct). All other comments should occur in public on the corresponding issue.
    • If the author needs to make a change to the (private) pull request, simply update the original branch which is being used as the source for the pull request. Github will automatically update the pull request.
  3. After the issue has passed the second vote, the MPI Standard Document Editor can merge the pull request by clicking the Merge Pull Request button.
    • This will automatically merge the branch associated with the pull request with the most recent version of the branch which the pull request is targeting.
    • If the pull request's branch has deviated from the original branch, the original author and/or chapter committees may need to review any conflicts and update the pull request.
  4. If the appropriate text was used in the description of the pull request, both the issue and the pull request should now be closed and merged into the main repository for the appropriate version of the MPI Standard.