MPI Standard Document Editor RC Guidelines

The MPI Standard Document Editor is responsible for producing at least two release candidate documents as part of the process of ratifying a new version of the MPI Standard. This document has some guidelines on how to manage that document with Git and GitHub with the MPI Forum’s current tooling.

Git Branches

The MPI Forum repository typically uses two branches for managing the MPI Standard Document: mpi-3.x for any releases in the MPI 3 series, and mpi-4.x for any releases in the MPI 4 series. For the purposes of releasing the MPI 4.0 document, we will temporarily add a third branch: mpi-4-rc.

This new branch will be used to generate all release candidate documents and the main difference between it and the mpi-4.x branch is that it will include PRs that have not yet been voted into the main branch to facilitate votes on the release candidate before the final document is finished.

While the main branches are managed via GitHub, the release candidate branch will need to be managed on the command line, due to the inability to merge a single pull request into two separate branches. The workflow for this is below.

Release Candidate Workflow

Chapter committees, working groups, and individual contributors will create pull requests against the mpi-4.x branch because this is where the final version of the MPI 4.0 document will be generated. Once the PR has been reviewed by all necessary groups and is ready to be included in the RC document, the document editor will need to merge this PR manually on the command line.

While there are multiple ways to accomplish this, my (Wes’s) recommendation is to install and use the Hub open-source tool written by GitHub: https://hub.github.com. This tool allows you to locally merge pull requests by directly copying the URL of the pull request into the terminal. An example workflow is below and assumes a local checkout of the MPI Standard repository with at least one remote named mpi-forum that looks like this (you may have more):

$ git remote -v
mpi-forum	https://github.com/mpi-forum/mpi-standard (fetch)
mpi-forum	https://github.com/mpi-forum/mpi-standard (push)
wgropp	https://github.com/wgropp/mpi-standard (fetch)
wgropp	https://github.com/wgropp/mpi-standard (push)

First, the mpi-4-rc branch needs to be created. This will need to happen after all pre-RC PR have been merged into the mpi-4-x branch. If it has not yet been created in the main repository on GitHub, you can create it locally like this:

# Check out the latest version of the mpi-4.x branch from the main repository
$ git checkout mpi-4.x

# Pull in the latest changes to the mpi-4.x branch from the main respository on GitHub
$ git pull mpi-forum mpi-4.x

# Create the new RC branch based on the current mpi-4.x branch
$ git checkout -b mpi-4-rc

This is a sample of how to merge a pull request into your local mpi-4-rc branch:

# Check out the local mpi-4-rc branch
$ git checkout mpi-4-rc

# Pull in the latest changes to the mpi-4-rc branch from the main respository on GitHub
$ git pull mpi-forum mpi-4-rc

# Merge the upstream PR into the mpi-4-rc branch
$ hub merge https://github.com/mpi-forum/mpi-standard/pull/1234

# Resolve any conflicts if necessary. To see if there are any conflicts and get instructions
# on how to mark them as resolved, check the status. It is possible that there will be conflicts
# that appear when merging locally that do not show up on the pull request page on GitHub
# becuase the pull request targets mpi-4.x  while the local branch is being merged into mpi-4-rc.
$ git status

# After the pull request has been merged locally (and any conflicts resolved, if necessary, confirm
# that the branch looks correct by looking at a simplified version of the Git log. I set this as an
# in my shell to glol.
$ git log --graph --pretty='\''%Cred%h%Creset -%C(auto)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'\'

# If that graph looks correct, push the new version of the mpi-4-rc branch to GitHub
$ git push mpi-forum mpi-4-rc

# This will prompt you to create a pull request, but that can be ignored as we will not be merging
# the mpi-4-rc branch back into the mpi-4.x branch

GitHub has a help page with some guidance on how to resolve Git merge conflicts on the command line: https://docs.github.com/en/free-pro-team@latest/github/collaborating-with-issues-and-pull-requests/resolving-a-merge-conflict-using-the-command-line

Synchronizing With the mpi-4.x Branch

As pull requests are merged into the mpi-4.x branch as part of the review and voting process, the mpi-4-rc branch will need to periodically be merged with the main mpi-4.x branch. This will be true in particular after the RCM where many of the issues will addressed and the fixes voted into the main document. Because each of the pull requests will be created with mpi-4.x as the base branch, these PRs can be merged normally to update the main document.

To keep the mpi-4-rc branch in sync, use a simple git merge and resolve any conflicts (if necessary):

# Check out the latest version of the mpi-4-rc branch
$ git checkout mpi-4-rc
$ git pull mpi-forum mpi-4-rc

# Fetch (but do not yet merge) the latest version of the mpi-4.x branch
$ git fetch mpi-forum

# Now that the local metadata for the mpi-4.x branch is up to date, merge the two branches locally
$ git merge mpi-forum/mpi-4.x

# Resolve any conflicts if necessary. To see if there are any conflicts and get instructions
# on how to mark them as resolved, check the status.
$ git status

# After the pull request has been merged locally (and any conflicts resolved, if necessary, confirm
# that the branch looks correct by looking at a simplified version of the Git log. I set this as an
# in my shell to glol (git log oneline).
$ git log --graph --pretty='\''%Cred%h%Creset -%C(auto)%d%Creset %s %Cgreen(%cr) %C(bold blue)<%an>%Creset'\'

# If that graph looks correct, push the new version of the mpi-4-rc branch to GitHub
$ git push mpi-forum mpi-4-rc

# This will prompt you to create a pull request, but that can be ignored as we will not be merging
# the mpi-4-rc branch back into the mpi-4.x branch