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 Fault Tolerance Working Group.

[Another example](Working Group Example 2) shows how the Tools 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 Fault Tolerance Working Group, there are two types of branches that are stored in the mpi-standard repository.

• First, small branches which cover relatively small topics live at the top level of the repository. This means that for tickets with short changes that can be accomplished in few lines with a single commit, the working group creates a branch within the main working group repository which branches from the desired main branch. Such small branches will usually branch from the current main branch, which is mpi-3.x. An example of how this looks is below:

* bf12f8c6 (HEAD -> cleanup-free) Clarify what is valid to do with a communciator after freeing
| * de2ab652 (errors-abort) Remove LaTeX markup for tickets
| * beb95365 Create new error handler MPI_ERRORS_ABORT
| * 51ea8213 (cleanup-errhandlers) Remove LaTeX markup for tickets
| * 51078dac Remove the ticket to create MPI_ERRORS_ABORT from this branch to keep things clean
| * b48f7cb2 Change issue numbers to GitHub numbers
| * 0e4ef760 Edits from the sept-15 meeting
| * f32ba615 Fix error with change macros
| * bfcef500 Fix wording around (P)MPI_ABORT
| * 06371800 Fix wording in call_errhandler
| * 873e0dfc Reword advice per Fab suggestion
| * 2443b8b6 Minor fixes from after-forum discussions
| * 5882060c Implementation bugfixes
| * b0bd37de Define errhandler semantics for communicator creation functions
| * 437aaaac Specify inheritance for errhandlers in comms and wins
| * 08b3ff4e Make a callout from 8.3 to 2.8 at the request of Rolf
| * f273b751 Integrate changes from 2015-06-02 feedback
| * 7e528dac Fix small errors from reading.
| * 3dd11b1a Add advice about cleanly dealing with abort/non-abort mix
| * 2af1af4a Add phrase camping the new text in the context
| * d2b26add Add original text from Josh
|/
| * 7c5f9068 (free-advice) Remove paragraph from MPI_COMM_FREE advice.
|/
* 1ee795db (myfork/mpi-3.x, mpi-standard/mpi-3.x, mpi-standard/HEAD, ftwg/mpi-3.x, mpi-3.x) Clean up the figures

Note how, for the most part, each of these branches (cleanup-free, free-advice, cleanup-errhandlers) branches directly from mpi-3.x. One of the branches (errors-abort) depends on some of the work in cleanup-errhandlers and therefore is created from the cleanup-errhandlers branch rather than mpi-3.x.

• The second type of branch is for long-lived projects that involve the collaboration of multiple members of the working group. In the Fault Tolerance Working Group, User Level Failure Mitigation (ULFM) is such a project. For this type of work, multiple branches are used and each is named in a way to make it clear that branches belong together. For ULFM, this means that all branches have the prefix ulfm/. There is a single branch in the ulfm namespace called ulfm/master which integrates the current status of the ULFM work. Other branches in the ulfm/ namespace are for work that is not yet part of the ULFM proposal, but being discussed within the working group.

* 55940f0c (ftwg/ulfm/ishrink) Create MPI_COMM_ISHRINK
| | * 355264a8 (ftwg/ulfm/rma-flushadvice) add 'correctly' to "cannot complete"
| | * 28506088 Adding a flush advice (from discussion with J. Hammond)
| |/
| *   4f90cd2b (HEAD -> ulfm/master, ftwg/ulfm/master) Merge remote-tracking branch 'mpi-3.x' into ulfm
| |\
| |/
|/|
| * a2d5236c Remove the working group directory
| *   3751df05 Merged in bouteill/mpi3ft/rma-memcorrupt (pull request #56)
| |\
| | * 8d03c5e4 accumulate=update+read&update+cas
| | * 7638f32e Accounting for latest round of remarks on the memcorrupt text
| | *   18b3ffde Merged default into rma-memcorrupt
| | |\
| | |/
| |/|
| * |   cace4392 Merged in bouteill/mpi3ft (pull request #58)
| |\ \
| | * | 1967de9f Typo reported by Geoffroy
| * | | e6be5d14 More figure cleanup
| * | | be75724c Clean up the repository a bit
| |/ /
| | * e9627102 Grammar.
| | * dee2fdad Taking into account wesley's comment: moving closer to the normative text the advice to remind users that they are in charge
| | * 35993ae9 Adding an example for clarity

In this example, you can see the ftwg/ulfm/master branch which is continually merged with the mpi-3.x branch from the mpi-forum/mpi-standard repository. Other branches include ftwg/ulfm/ishrink and ftwg/ulfm/rma-flushadvice which are topics still being discussed and not ready to be included in the main ftwg/ulfm/master branch.

Pull Requests

There are two types of pull requests in the Fault Tolerance Working Group, internal pull requests and external pull requests.

• External pull requests work similarly to the example in Creating Simple Pull Request. When a branch within the working group is ready to be considered by the full MPI Forum, an issue is filed in mpi-forum/mpi-issues and someone within the working group (usually the author of the ticket) creates a pull request from the mpiwg-ft/mpi-standard repository on GitHub to the mpi-forum/mpi-standard repository. This follows all of the same rules and guidelines as the previous guide and those found in How to file an MPI Forum issue ("ticket").

• Internal pull requests are for work being merged from a topic branch inside a larger project to the master bracnh within the project. In the example above, a pull request could merge the work in ftwg/ulfm/ishrink with ftwg/ulfm/master. Internal pull requests are created in the same way as external pull requests, but the source and destination repositories are the same. When beginning a pull request from an internal branch, GitHub will usually prompt to submit the pull request back to the mpi-forum/mpi-standard repository because the working group repository is a fork of that repository. Your browser will probably look something like this:

You should change the "base fork:" on the left side of the pull request to be the working group where you are doing your work. In our case, mpiwg-ft/mpi-standard. This will cause the GitHub page to change and not show the "base fork:" or "head fork:" anymore. It will only show the "base:" and "compare:" branches. Now we change the "base:" branch to ulfm/master and leave the "compare:" branch as ulfm/example. So our completed pull request looks like this:

Now you can push the green "Create pull request" button and the pull request will be added to the mpiwg-ft/mpi-standard repository under the pull requests tab on the right side of the page. Here, the working group can make comments before merging the pull request back into the main branch. When the pull request is ready to be merged into the main branch, someone within the working group can click the green "Merge Pull Request" button which will take them through the steps of merging a pull request. To see these changes locally, use the command git fetch ftwg --prune which will update your local version of the ftwg remote with all of the changes in the mpiwg-ft repository from GitHub and prune any branches which you have locally where the accompanying remote branch has been deleted.

When clicking the "Merge pull request" button, there should be a green checkmark indicating that the branch can be merged automatically. If the pull request conflicts with work that someone else has done to the same file after your branch was created, there may be a message indicating such a scenario. In this case, you will need to update your pull request.

Updating a Pull Request

If you need to update your pull request, either because you want to make changes based on working group discussions or because a merge conflict needs to be resolved, this is as simple as making changes to the branch on which the pull request is based. Locally, you can create new commits on the same branch which add the new features or resolve the conflicts. When you are satisfied with the updated branch, push the new changes back to the working group remote on the same branch as the original pull request. GitHub will automatically update the pull request with the latest version of your branch. Updating a pull request is generally the only time that it is ok to have commits which change the Git history, sometimes called non-fast-forward changes.