Working Group Example 2 - mpi-forum/mpi-issues GitHub Wiki

This page gives an example of one possible way of using working group organizations to keep track of issues, branches, and pull requests within a working group. This model is the one used by the Tools Working Group (TWG).

[Another example](Working Group Example 1) shows how the Fault Tolerance Working Group operates.

In this guide, we assume that your repository is set up in the same way as the Initial Git setup guide.

Organization Setup

As with the main mpi-forum organization, the working groups have two main repositories.

  • The first, mpi-standard, is a fork of the mpi-forum/mpi-standard repository and is kept private. The source code for the MPI Standard is in this repository and it can be used as a sandbox for the working groups to draft proposals before submitting them as pull requests to the MPI Forum.

  • The second repository, <wg>-issues, is named differently for each working group, but is the public space where the working group can house its wiki pages and issues to let anyone view and make comments. This repository does not have any actual code as it is kept in the mpi-standard repository.

More details for how the working groups are set up can be found in the Working Group Guidelines guide.

Branch Management

The main difference in how working groups operate comes from branch management. In the TWG, there are three types of branches that are stored in its repositories. The descriptions below refer to

  1. Branches tracking the main mpi-forum/mpi-standard repository. These branches include mpi-3.x, mpi-2.x, etc. These branches are kept in sync with the their counterpart branches in the upstream mpi-forum/mpi-standard repository.
  2. Git feature branches. These are branches created by Working Group members for text changes that they want the Working Group to review (before going up to the full MPI Forum). These branches are used for pull requests to the integration branch.
  3. integration branches. There is an integration branch for each tracking branch (e.g., the mpi-3.x tracking branch has a corresponding integration-mpi-3.x integration branch). These integration branches are the pull request targets for Tools Working Group feature branches. The purpose of these branch are so that the TWG can build a full copy of the MPI standard document with all their proposed changes that have not yet been accepted in to the upstream mpi-forum/mpi-standard repository yet.
  • NOTE: Integration branches are created as necessary. For example, as of this writing (21 Oct 2015), there is no integration-mpi-3.x branch because the TWG hasn't created any pull requests against the MPI-3.1 document yet.

The Tools repository looks like the repo on the right hand side of this image:

MPI Forum working group workflow option 2

Tracking branches

The branches that track their corresponding branches in mpi-forum/mpi-standard (e.g., the mpi-3.x branch) are kept in sync with their upstream counterparts.

For example, any new commits that appear on the mpi-3.x branch in mpi-forum/mpi-standard need to be synced down to the mpi-3.x branch in the mpiwg-tools/mpi-standard. This sync can be performed by a human periodically, or in an automated fashion (e.g., via a cron job).

Feature branches

The TWG repository is writable by all TWG members. Hence, any TWG member can create and edit feature branches (even if a different TWG member created the feature branch). This allows collaborative work across the entire TWG.

integration branches

The integration branches receives updates from two sources:

  1. Each integration branch periodically synced with new commits from its corresponding tracking branch. For example, after mpi-3.x is updated from its corresponding branch in mpi-forum/mpi-standard, it is then merged into integration-mpi-3.x.
  2. Each integration branch is the target of pull requests in the TWG.

Workflow for internal TWG proposals

The general workflow for a TWG member to propose new text is threefold:

  1. File an issue + pull request in the mpiwg-tools organization.
  2. Discuss the proposal in the Working Group. Merge the pull request when consensus is reached.
  3. File a corresponding issue + pull request in the mpi-forum organization.

File issue + pull request in the TWG

  1. TWG member creates a public issue in mpiwg-tools/tools-issues.
  2. TWG member creates a feature branch in mpiwg-tools/mpi-standard and pushes commits with the proposed text changes.
  3. TWG creates a private pull request in mpiwg-tools/mpi-standard.
    • The target is the integration branch on the mpiwg-tools/mpi-standard repository.
    • The source is the feature branch that the TWG member just pushed to the same mpiwg-tools/mpi-standard repository (yes, you can have a pull request source and target in the same repository).

TWG discusses the proposal

  1. TWG discusses the pull request. The pull request may get modified during the course of the TWG discussions.
  2. Once consensus is reached and the pull request is ready, it is merged to the integration branch.

File issue + pull request in the main MPI Forum

Essentially repeat the above procedure, but:

Yes, the source branch is the same feature branch in the mpiwg-tools/mpi-standard in for both the internal TWG pull request and the full MPI Forum pull request. This actually guarantees that the text discussed in the TWG is exactly the same as what is presented to the full MPI Forum.