Chapter Committee Ratification Guidelines - mpi-forum/mpi-issues GitHub Wiki

Before ratifying a new version of the MPI Standard, the chapter committees are responsible for reviewing their respective chapters and reporting any issues to the MPI Forum Chair and Secretary to be resolved.

Review the Document

The document can be reviewed in any way that makes sense, but the committees should do it in a way that makes all changes obvious. The recommended way to do this is with a built-in diff tool from Git. To begin, check out the latest version of the document to be reviewed.

Set Up Local Repository

The examples below will assume that the user has a Git remote set up in this way:

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

If this isn't true for your system, you can replace mpi-forum with whatever you've called your remote for the main MPI Forum repository (e.g., origin).

After your remote is set up, fetch the latest version of the repository:

$ git fetch mpi-forum

Check Out Latest Version of Branch

The check out the branch to be reviewed. For the MPI 4.0 ratification cycle, we will use the branch mpi-4-rc as the branch for the combined document to be reviewed (as opposed to the mpi-4.x branch which is only for things that have been finally voted into the MPI Standard Document).

$ git checkout -b mpi-4-rc mpi-forum/mpi-4-rc

You may need to update your local checkout as changes are made in the main repository on GitHub. To do this, follow these steps:

$ git checkout mpi-4-rc
$ git pull mpi-forum mpi-4-rc

Use git diff to Review Document

Once you have the correct version of the document checked out, you can use a diff tool to review the differences between the last released version of the document and the version being reviewed.

For example:

$ git diff mpi-3.1 chap-inquiry

Depending on the chapter, there are a variety of options that may make the chapter diff more readable. For example, in the MPI 4.0 review, the tools chapter is probably reviewed more easily by look at a diff on a word-by-word basis rather than a line-by-line basis.

$ git diff --ignore-all-space --color-words mpi-3.1 chap-tools

Note Necessary Changes

While reviewing, the committee should note any items, big and small, that need to be corrected before ratifying MPI 4.0. For each item, the chapter committee should open a GitHub issue and assign these tags to it: mpi-4.0, final-review, the tag for the appropriate chapter (e.g., chap-contexts), and either errata or Chapter Committee Change (depending on the scope). Also add the issue to the MPI 4.0 Ratification project so we can track the status on the project page.

If you are having trouble with any of these steps, contact Wes for help.

Once the necessary changes are itemized, the committee can begin making the changes as pull requests. It is acceptable for multiple changes of the same type to be corrected in a single pull request (e.g., chapter committee changes can be combined or errata-level changes can be combined, not chapter committee and errata in the same PR), but each change being corrected needs to be noted in the pull request description. Use this text in the PR description for each issue being addressed: Closes mpi-forum/mpi-issues#12345. The pull request should use mpi-4.x as the "base branch".

Present Changes Since MPI 3.1

The chapter committee is also responsible for showing a list of all changes to the MPI Forum at the RCM. This can be done with slides, a colorized PDF, or a Git diff. Use whatever tool makes sense for the chapter and presenter.