This page gives a simple example of creating a new pull request and accompanying issue using the MPI Forum GitHub page.

Note that it is more common for issues to be presented to a Working Group first, where they will be discussed before being discussed with the full MPI Forum. Other wiki pages will cover workflows of issues and pull requests flowing through Working Groups; this guide provides the simplest example for those who are unfamiliar with Git and GitHub pull requests..

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

Before we do any work in the source of the MPI Standard, we should first create a new issue on the mpi-forum/mpi-issues repository. For our example, we will be creating a new API function called MPI_AWESOME.

1. Click to create a new issue on the public mpi-forum/mpi-issues repository.
2. Fill in a good title for the issue.
3. Fill in a good description for the issue.
4. Pick appropriate labels for the issue (off to the right).
5. Pick an appropriate milestone for the issue (off to the right, below the labels).

For example:

.6. Click the green "Submit new issue" button.

Now the issue is created and includes all of the important information mentioned in the How to file an MPI Forum issue ("ticket") guide. Our new issue looks like this:

Note that the issue number is mpi-forum/mpi-issues#8. This will be important later.

Once you have created the public issue, then you need to edit LaTeX source files to effect your proposed change, push them to your personal GitHub fork, and then create a private pull request to request to bring those changes to the official MPI Forum git repository.

Before starting, make sure that we have the most up to date changes from the main mpi-forum/mpi-standard repository. This can be done by pulling that changes into our local Git repository.

First, we should checkout the branch where we will be basing our work. Here, we will assume that our issue is related to MPI-3, and will therefore use the branch mpi-3.x. If your issue applies to multiple versions of MPI (for example, it applies to MPI-3.x and MPI-4.x hasn't been released yet to close the 3.x line), use the earliest version of MPI and when the pull request is merged, it can be re-applied to the later branches.

$ git checkout mpi-3.x
Switched to branch 'mpi-3.x'
Your branch is up-to-date with 'mpi-standard/mpi-3.x'.

If your local branch is not in sync with the mpi-standard repository, the bottom line above will look different:

$ git checkout mpi-3.x
Switched to branch 'mpi-3.x'
Your branch is behind 'mpi-standard/mpi-3.x' by 8 commits, and can be fast-forwarded.
  (use "git pull" to update your local branch)

If this is the case, you can update your local repository by pulling from the mpi-standard repository.

$ git pull mpi-standard mpi-3.x
From github.com:mpi-forum/mpi-standard
 * branch              mpi-3.x    -> FETCH_HEAD
First, rewinding head to replay your work on top of it...
Fast-forwarded mpi-3.x to 1ee795dbf399b58198bfec5aed60c0f2716de97c.

GitHub pull requests work best when you make a branch off the source branch. That is, you make a branch off the tip of the mpi-3.x branch (this is often called a Git "feature branch").

For this example, our branch will be called mpi-awesome:

$ git checkout -b mpi-awesome
Switched to a new branch 'mpi-awesome'

The checkout -b command both creates a branch called mpi-awesome and switches to that branch (as with everything in Git, there are multiple ways of doing this -- but we're keeping it simple here).

For this example, we'll assume the new function MPI_AWESOME belongs in the inquiry chapter. We made some edits to the inquiry .tex files, and of course, we also added an entry to the changelog. To see that we made these changes, run the following command:

$ git status
On branch mpi-awesome
Changes not staged for commit:
  (use "git add <file>..." to update what will be committed)
  (use "git checkout -- <file>..." to discard changes in working directory)

	modified:   chap-changes/changes.tex
	modified:   chap-inquiry/inquiry.tex

no changes added to commit (use "git add" and/or "git commit -a")

To see the full change, use git diff:

$ git diff
diff --git a/chap-changes/changes.tex b/chap-changes/changes.tex
index 79b111a8..3d524521 100644
--- a/chap-changes/changes.tex
+++ b/chap-changes/changes.tex
@@ -17,6 +17,14 @@ version of the standard.
\section{Changes from Version 3.1 to Version 3.2}
\label{subsec:31to32}
+
+\item
+Section~\ref{sec:inquiry-startup}.
+\newline
+Added \mpifunc{MPI\_AWESOME}.
+

 \section{Changes from Version 3.0 to Version 3.1}
 \label{subsec:30to31}
diff --git a/chap-inquiry/inquiry.tex b/chap-inquiry/inquiry.tex
index fc835674..b38383f0 100644
--- a/chap-inquiry/inquiry.tex
+++ b/chap-inquiry/inquiry.tex
@@ -1889,6 +1889,17 @@ in callback functions that are invoked during \mpifunc{MPI\_FINALIZE}.
 \end{users}


+\begin{funcdefna}{MPI\_AWESOME()}
+\end{funcdefna}
+
+\mpibind{MPI\_Awesome(void)}
+
+\mpifnewbind{MPI\_Awesome(ierror) \fargs INTEGER, OPTIONAL, INTENT(OUT) :: ierror}
+\mpifbind{MPI\_AWESOME(IERROR)\fargs INTEGER IERROR}
+
+This routine runs the entire program instantly and produces a correct answer. 
+It never returns an error because it cannot be wrong.
+
 %%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%
 \section{Portable \texorpdfstring{\MPI/}{MPI} Process Startup}
 \mpitermtitleindex{startup!portable}

As the git status command above pointed out, the changes that we've made are not currently staged for commit.

Git has a notion of a "staging area" where changes are put before they are committed. This allows you to easily keep track of what you are and are not about to commit before actually doing it.

For this example, we need to add the two files we've edited to the staging area:

$ git add chap-changes/changes.tex
$ git add chap-inquiry/inquiry.tex
$ git status
On branch mpi-awesome
Changes to be committed:
  (use "git reset HEAD <file>..." to unstage)

	modified:   chap-changes/changes.tex
	modified:   chap-inquiry/inquiry.tex

NOTE: A major difference between Subversion and Git is that Git tracks differences, not files. For example, if you edit changes.tex and then git add it, but then make further edits to changes.tex, you need to git add it again to stage the second set of changes.

Our changes are now ready to be committed. We should create a good commit message which will allow us to easily find the issue that we opened earlier. To do so, make sure that you mention the GitHub absolute reference to the mpi-issues issue number 8: mpi-forum/mpi-issues#8 (which we created earlier).

$ cat commit-message
Create MPI_AWESOME

Create the new API call MPI_AWESOME.

Closes mpi-forum/mpi-issues#8.
$ git commit -F commit-message
[mpi-awesome 270c4462] Create MPI_AWESOME
 2 files changed, 18 insertions(+)

Of course, you don't have to put your commit message in a file first. If you just type git commit, you will be presented with a text editor where you can write your message.

We can now see that we've made local changes if we look at the graph of our commits. Here, we use the command git graph, but note that this isn't a command that comes with Git. We set it up during the Initial Git Setup guide. If you haven't set up with that guide, the command is git log --graph --decorate --abbrev-commit --pretty=oneline

$ git graph
* 270c4462 (HEAD -> mpi-awesome) Create MPI_AWESOME
* 1ee795db (myfork/mpi-3.x, mpi-standard/mpi-3.x, mpi-standard/HEAD, ftwg/mpi-3.x, mpi-3.x) Clean up the figures directory
* 632eba18 Remove files only applicable to previous versions.
* 68fd150a Bump version to 3.2
* e81fb265 Add gitignore file
* 0a5704e2 Set the build with changeonlyplustickets to show deletions
* 12d20324 Set drafttrue by default
* e28be80c ticket-0 fix
* 10eec586 Added typo report
* 7988c956 (tag: mpi-3.1) Add MPI 3.1 Document
* 2e17ae95 Final updates for HTML version
* f815aa20 Final updates for 3.1.  This version was posted

We can see here that there is a new branch called mpi-awesome that is only in our local repository and not yet on any of the remotes. For others to be able to see these changes, we need to push them to our remote user repository, which we've called myfork.

$ git push myfork mpi-awesome
Counting objects: 6, done.
Delta compression using up to 4 threads.
Compressing objects: 100% (6/6), done.
Writing objects: 100% (6/6), 890 bytes | 0 bytes/s, done.
Total 6 (delta 3), reused 0 (delta 0)
To [email protected]:wesbland/mpi-standard.git
 * [new branch]        mpi-awesome -> mpi-awesome

Now we can see that the branch is both on our local version of the repository and the myfork remote:

$ git graph
* 270c4462 (HEAD -> mpi-awesome, myfork/mpi-awesome) Create MPI_AWESOME
* 1ee795db (myfork/mpi-3.x, mpi-standard/mpi-3.x, mpi-standard/HEAD, ftwg/mpi-3.x, mpi-3.x) Clean up the figures directory
* 632eba18 Remove files only applicable to previous versions.
* 68fd150a Bump version to 3.2
* e81fb265 Add gitignore file
* 0a5704e2 Set the build with changeonlyplustickets to show deletions
* 12d20324 Set drafttrue by default
* e28be80c ticket-0 fix
* 10eec586 Added typo report
* 7988c956 (tag: mpi-3.1) Add MPI 3.1 Document
* 2e17ae95 Final updates for HTML version
* f815aa20 Final updates for 3.1.  This version was posted

Now that we have our changes pushed to the myfork remote (which is simply a name that refers to your personal Git repository that is a fork of the corresponding MPI Forum repository -- in this example, it refers to wesbland/mpi-standard), it's time to create the pull request back to the mpi-forum/mpi-standard repository.

Pull requests are a feature of GitHub which allow us to see how the changes in a branch in one repository would impact a branch another repository, and then easily merge the two together. In this case, we want to pull the changes in our mpi-awesome branch in the wesbland/mpi-awesome repository to the mpi-3.x branch in the mpi-forum/mpi-standard repository.

If you go to your fork of the mpi-standard repository on GitHub within a few minutes of pushing to the mpi-awesome branch on the myfork remote, the page will look something like this:

Note that there is a green button in the middle labeled "Compare & pull request". This is GitHub noticing that you just pushed a feature branch and assuming that you want to create a pull request.

If it's been more than a few minutes since you pushed to the feature branch, the green button may not be there automatically. Have no fear! You can still manually create the pull request. Go to the branches list by clicking the "Branches" link at the top of the page. You'll see a list of all of your branches and you can click the "New pull request" button next to the mpi-awesome branch.

If you don't participate in any Working Group organizations yet, the pull request on the next page should be pre-populated with all of the correct information. If you're already involved in some working groups, you may need to adjust a few things.

REMEMBER: This example is showing how to create a pull request directly back to the main MPI Forum repository. Making pull requests through Working Group organizations are described on other wiki pages.

• On the left side (i.e., the destination):
  • Make sure that the "base fork:" on the left side of the pull request is the mpi-forum/mpi-standard repository instead of any Working Groups which which you are involved.
  • The next box is the branch that the pull request will be merged into. This should point to the version of the MPI Standard that the issue should apply to first. In our case, this is mpi-3.x.
• On the right sice (i.e., the source):
  • The "base fork:" should be your personal GitHub fork wesbland/mpi-standard
  • The branch should be mpi-awesome.

Below this, if your branch is a single commit, the description of the pull request will be pre-populated with the message from that commit. If it's more than a single commit, you will need to write your own message here. Make sure to reference the issue solved by this pull request (i.e., the text mpi-forum/mpi-issues#8); GitHub will auto-link that text in the pull request description back to the corresponding public issue.

Continuing down the page, you can see the union of all the diffs that are introduced by the pull request.

When you're ready to create the pull request, push the green "Create pull request" button.

If you put the correct text in the description, it should become a link to the issue in the mpi-forum/mpi-issues repository. If you go back to that issue, you should also see a link to the pull request.

After the pull request has been created and submitted, it's time to go through the normal process of moving an issue through the MPI Forum. You'll need to do the usual readings, votes, etc., and can use the GitHub tools available to you to help with this process.

As the issue moves through the process, you can update the labels on the issue to reflect its current status and the milestone should show the next meeting where progress will be made.