Initial Git Setup

Obtaining Git

You can obtain source releases from http://git-scm.com/. Alternatively, most operating systems have a way to obtain a modern version of Git through the package management system (e.g, yum, brew, etc.).

Configuring Git

Add the following to your ~/.gitconfig file. Don't forget to change the user name/email!

[user]
        name = Joe Developer
        email = joe@example.org

[color]
        diff = auto
        status = auto
        branch = auto
        ui = auto

# optional, but helps to distinguish between changed and untracked files
[color "status"]
        added = green
        changed = red
        untracked = magenta

# optional, but allows git to create 8-character abbreviated hashes, that are "trac-compatible" for automatic link generation in the comments.
[core]
        whitespace = trailing-space,space-before-tab,indent-with-tab
        abbrev = 8

# optional, but allows better view of commits
[alias]
        graph = log --graph --decorate --abbrev-commit --pretty=oneline

Obtaining a GitHub Account

Sign up right on the home page at https://github.com/. If you expect to also have direct commit privileges to open-mpi/ompi:master, then send a mail to devel-core@open-mpi.org so that someone can add you to the open-mpi organization. Note that in order to commit directly you need to have signed the Open MPI Contributor License Agreement. See https://www.open-mpi.org/community/contribute/

Configuring git to Talk to GitHub

Please see the GitHub article on this topic.

OPTIONAL: Installing gh and hub on OS X

(These packages enable some interactions with GitHub via the command line.)

Install Homebrew: http://brew.sh/

Then:

$ brew install npm
...

$ sudo npm install -g gh
...

$ brew install hub
...

### configure credentials (my account is set up for 2FA)
### token came from: https://help.github.com/articles/creating-an-access-token-for-command-line-use
$ cat ~/.gh.json
{
    "github_user": "goodell",
    "github_token": "0123456789abcdef0123456789abcdef01234567"
}

OPTIONAL: Installing gh On RHEL

(Note: the RHEL instructions probably require the EPEL repository)

### install the Node Package Manager
$ sudo yum install npm
...

### install the "gh" package to get the "gh" command
$ sudo npm install -g gh
...

### configure credentials (my account is set up for 2FA)
### token came from: https://help.github.com/articles/creating-an-access-token-for-command-line-use
$ cat ~/.gh.json
{
    "github_user": "goodell",
    "github_token": "0123456789abcdef0123456789abcdef01234567"
}

OPTIONAL: Installing hub On RHEL

(Note: the RHEL instructions probably require the EPEL repository)

$ sudo yum install rubygem-rake
...

$ git clone https://github.com/github/hub.git
...

$ cd hub

$ rake install prefix=/path/to/install/root
...

Setting Up A New Local Developer Repository

Here we clone the primary Open MPI repository to our local machine. This gives us a complete local copy of the repository history.

$ git clone git@github.com:open-mpi-demo/ompi.git
Cloning into 'ompi'...
remote: Counting objects: 250629, done.
remote: Compressing objects: 100% (42816/42816), done.
remote: Total 250629 (delta 206704), reused 250629 (delta 206704)
Receiving objects: 100% (250629/250629), 67.77 MiB | 12.65 MiB/s, done.
Resolving deltas: 100% (206704/206704), done.
Checking connectivity... done.

$ git remote add release git@github.com:open-mpi-demo/ompi-release.git

$ git fetch release
warning: no common commits
remote: Counting objects: 231486, done.
remote: Compressing objects: 100% (39315/39315), done.
remote: Total 231486 (delta 191101), reused 231486 (delta 191101)
Receiving objects: 100% (231486/231486), 62.70 MiB | 12.39 MiB/s, done.
Resolving deltas: 100% (191101/191101), done.
From github.com:open-mpi-demo/ompi-release
 * [new branch]      v1.7       -> release/v1.7
 * [new branch]      v1.8       -> release/v1.8

Now at this point we also want to create a user fork of open-mpi-demo/ompi-release on the GitHub site. This user fork will be used to submit pull requests back to the restricted release branches (e.g., 1.8 and 1.9). We can do this via the web interface by visiting: https://github.com/open-mpi-demo/ompi-release/fork

You can also do this with the gh command if you already installed it:

$ gh repo --fork ompi-release --user open-mpi-demo
gh [info] Forking repo open-mpi-demo/ompi-release on goodell/ompi-release
gh [success] https://github.com/goodell/ompi-release

$ git remote add goodell https://github.com/goodell/ompi-release

Workflow For Cherry-Pick Model

Adding a New Fix/Feature to open-mpi/ompi:master

This example demonstrates creating a topic branch, checking it out, and then creating two commits on that new branch. Then the topic branch is merged back to master and pushed up to GitHub.

$ git checkout -b topic/fix-examples master

$ vim examples/ring_c.c
...

$ git diff
diff --git a/examples/ring_c.c b/examples/ring_c.c
index 353be3b..19b10f2 100644
--- a/examples/ring_c.c
+++ b/examples/ring_c.c
@@ -54,7 +54,7 @@ int main(int argc, char *argv[])
 
         if (0 == rank) {
             --message;
-            printf("Process 0 decremented value: %d\n", message);
+            printf("Process 0 DECREMENTED value: %d\n", message);
         }
 
         MPI_Send(&message, 1, MPI_INT, next, tag, MPI_COMM_WORLD);

$ git commit -a -m 'ring_c: turn up the volume!'
[topic/fix-examples 5b8249b] ring_c: turn up the volume!
 1 file changed, 1 insertion(+), 1 deletion(-)

$ vim examples/hello_mpifh.f
...

$ git diff
diff --git a/examples/hello_mpifh.f b/examples/hello_mpifh.f
index 238bf94..f66a111 100644
--- a/examples/hello_mpifh.f
+++ b/examples/hello_mpifh.f
@@ -7,6 +7,7 @@ C $COPYRIGHT$
 C
 C Sample MPI "hello world" application in Fortran 77
 C
+C Uses the *ANTIQUATED* mpif.h interface.
         program main
         implicit none
         include 'mpif.h'

$ git commit -a -m 'hello_mpifh: this example uses an old interface'
[topic/fix-examples 17aa2bf] hello_mpifh: this example uses an old interface
 1 file changed, 1 insertion(+)

$ git checkout master
Switched to branch 'master'
Your branch is up-to-date with 'origin/master'.

### not needed b/c it says we are up-to-date above, but would usually issue
### this command otherwise:
$ git pull --rebase
Current branch master is up to date.

### "--no-ff" can be omitted if "merge.ff=false" is set in your git
### configuration.  We usually want this for fixes/features comprised of more
### than one commit to make cherry picking easier later on.
$ git merge --no-ff topic/fix-examples
[drops you into $EDITOR to write a commit message]


$ git push origin master
Counting objects: 7, done.
Delta compression using up to 32 threads.
Compressing objects: 100% (4/4), done.
Writing objects: 100% (4/4), 382 bytes | 0 bytes/s, done.
Total 4 (delta 3), reused 0 (delta 0)
To git@github.com:open-mpi-demo/ompi.git
   a8540fe..5b8249b  master -> master

$ git log --oneline --decorate --graph | head -n 7
*   d9c7734 (HEAD, master) Merge branch 'topic/fix-examples'
|\  
| * 17aa2bf (topic/fix-examples) hello_mpifh: this example uses an old interface
| * 5b8249b ring_c: turn up the volume!
|/  
* a8540fe (origin/master, origin/HEAD) Fortran: add ompi/mpi/fortran/use-mpi-f08/mpi-f08-sizeof.F90 to the dist tarball.
* 184b497 Fortran: fix OMPI_GENERATE_F77_BINDINGS macro invokation

$ git push origin master
Counting objects: 13, done.
Delta compression using up to 32 threads.
Compressing objects: 100% (9/9), done.
Writing objects: 100% (9/9), 1002 bytes | 0 bytes/s, done.
Total 9 (delta 6), reused 0 (delta 0)
To git@github.com:open-mpi-demo/ompi.git
   a8540fe..d9c7734  master -> master

Fixing a Bug In Both master and v1.8

Start by performing the steps in the previous subsection to fix the bug on master. Then cherry pick the commit(s) to v1.8:

$ git fetch release
...

$ git checkout -b topic/fix-examples-v1.8 release/v1.8
Branch topic/fix-examples-v1.8 set up to track remote branch v1.8 from release.
Switched to a new branch 'topic/fix-examples-v1.8'

### figure out the commits to cherry-pick
$ git log --oneline topic/fix-examples
17aa2bf hello_mpifh: this example uses an old interface
5b8249b ring_c: turn up the volume!
a8540fe Fortran: add ompi/mpi/fortran/use-mpi-f08/mpi-f08-sizeof.F90 to the dist tarball.
184b497 Fortran: fix OMPI_GENERATE_F77_BINDINGS macro invokation
...

$ git cherry-pick a8540fe..topic/fix-examples
[topic/fix-examples-v1.8 3f4c4f2] ring_c: turn up the volume!
 1 file changed, 1 insertion(+), 1 deletion(-)
[topic/fix-examples-v1.8 209f14a] hello_mpifh: this example uses an old interface
 1 file changed, 1 insertion(+)

$ git push goodell topic/fix-examples-v1.8
Counting objects: 14, done.
Delta compression using up to 32 threads.
Compressing objects: 100% (8/8), done.
Writing objects: 100% (8/8), 808 bytes | 0 bytes/s, done.
Total 8 (delta 6), reused 0 (delta 0)
To git@github.com:goodell/ompi-release.git
 * [new branch]      topic/fix-examples-v1.8 -> topic/fix-examples-v1.8

And open a pull request, either:

1. Via the web. Goto https://github.com/goodell/ompi-release and click on "Compare & pull request".

2. Via the command line: hub pull-request -m "fix examples" -b open-mpi-demo/ompi-release:v1.8 -h goodell:topic/fix-examples-v1.8 (DJG: I think there's a way to do this with gh too, but I haven't sorted out the syntax yet)

The RM for the v1.8 release will then either approve the PR or request modifications. Assuming the PR is approved, the RM will perform the merge as part of approving the request (often with a one-click merge from the web UI).