Branch Management - mpi-forum/mpi-issues GitHub Wiki

The majority of this page is for the maintainers of the MPI Standard (document editor, chapter authors, etc.). In general, it does not apply to those submitting pull requests.

However, it is good to have an understanding of how we will organize things, so feel free to read on.

Branches

The MPI Standard document is maintained in Git with branches for each major version. This means all versions released with the major version 3.x will be in the branch named mpi-3.x.

Multiple Versions

At some point, the MPI Forum could be working on multiple versions of the Standard at the same time. For instance, if the MPI Forum is working on MPI 3.2 while simultaneously working on MPI 4.0, there will be an mpi-3.x branch and an mpi-4.x branch. Issues which are targeted for MPI 4.0 but not for MPI 3.2 should only be pushed into the mpi-4.x branch. However, all issues targeted for the mpi-3.x series will be applied to both branches. When creating a pull request, use the earliest branch (still being used) where your issue applies and the patches can be pulled forward into new branches as needed.

Merging with Multiple Versions

When issues are created and pull requests are submitted, they should be pulled against the earliest branch to which they will apply. For instance, an errata item for MPI 3.1 should be submitted against the mpi-3.x branch. After it has finished the review process detailed on the How to file an MPI Forum issue ("ticket") wiki page, it will be merged into the mpi-3.x branch. However, it should also be merged with the mpi-4.x branch (and any other later branch that exists). This process can be done most easily manually on a local copy of the repository by cherry-picking the commit from one branch to another and pushing the updated branch back to the main repository on GitHub.

Tagging Versions of the Standard

When the MPI Forum decides to ratify a version of the MPI Standard, the MPI Standard Document Editor (or their designee) should push a tag to the appropriate branch indicating the commit used to build that version of the document. For instance, if the MPI Forum creates version 3.2 of the MPI Standard, after the ratification process has completed in the face to face meeting, the editor will create a tag locally on the mpi-3.x branch called mpi-3.2. This branch should be pushed back to the main repository, indicating that the document is done.

Errata

Historically, the MPI Standard has not included adopted errata in the document until the next version of the Standard document. For instance, if errata were found in MPI 3.0, they were not inserted into the published version until MPI 3.1. This will continue in the Git workflow, but will be aided by the fact that all issues are automatically merged into the branch where they belong. This automatically applies them to the next version of the standard. The MPI Forum will still need to maintain a side document indicating the errata which will be published on the MPI Forum website separately. This document can be found within the MPI Standard repository itself. All errata pull requests should include only the change in the MPI Standard text. The MPI Standard Document Editor is responsible for maintaining the errata document. When publishing a new version of the MPI Standard, the errata document will be emptied.