1 of 29

MPI Forum:

Introduction to

Git and GitHub Goodness

November 2, 2015

2 of 29

RTFW (Read the Fine Wiki)

  • Getting started with Git
  • Getting started with GitHub
  • Workflows
    • Filing an issue (“ticket”)
    • Filing a pull request
  • Migrating from SVN / Trac

https://github.com/mpi-forum/mpi-issues/wiki

​

3 of 29

Git / GitHub terminology

  • Git: Distributed version control system
    • Subversion has a single “upstream”
    • Git can have multiple “upstreams”

​

  • GitHub(.com): hosting service
    • Repositories: Git repositories and associated tools
    • Organizations: Groups of GitHub repositories and users

​

4 of 29

General MPI Forum GitHub scheme

  • Organization:
    • mpi-forum
  • Repositories:
    • mpi-issues (public)
    • mpi-standard (private)
      • You must be a member of the mpi-fourm org to see the private mpi-standard repo
  • “Absolute” repo names:
    • mpi-forum/mpi-issues
    • mpi-forum/mpi-standard

5 of 29

General MPI Forum GitHub scheme

Issue

#28

​

Describe proposal

​

Attach PDFs

​

Refer to its corresponding PR (#107)

​

...etc.

(Public)

Pull Request #107

​

Easily see text / LaTeX diff

​

Should refer to its corresponding issue (#28)

​

​

​

(Private)

Git repo for LaTeX source code

(Private)

Wiki

(Public)

mpi-forum /

mpi-issues

(public)

mpi-forum /

mpi-standard

(private)

6 of 29

Who can access the source repo?

  • Anyone on the Forum
    • Just like previous access to SVN
  • New: Anyone who agrees to our rules
    • Don’t publish bogus copies of the Standard
    • Don’t publish the source publicly
    • ...etc.
    • https://github.com/mpi-forum/mpi-issues/wiki

7 of 29

Branch scheme

3.x branch

4.x branch

MPI 4.0

MPI 4.1

MPI 3.2

Git tags

MPI 3.0

MPI 3.1

https://github.com/mpi-forum/mpi-issues/wiki/Branch-Management

8 of 29

Typical proposal workflow

Create an issue:

describe the proposal

Create a pull request:

implement proposal in text

Link the issue and pull request

MPI Forum votes to approve the proposal

Get chapter committee to approve the pull request

(NEW)

Author

Editor

Forum

Chapter Committees

Pull request is merged

Chapter Committees / Authors help resolve merge issues (if any)

9 of 29

Errata Workflow

  • Authors make a pull request on the appropriate branch with:
    • Addition(s) to errata document (if there is one)
    • Corresponding change(s) in main document

​

  • When new version of MPI standard document released, errata document is cleared out

10 of 29

Errata Workflow (2)

3.x branch

MPI 3.2

Git tags

MPI 3.0

MPI 3.1

Pull request:

Clarify MPI_CANCEL for send requests (errata)

11 of 29

Proposal Workflow

  • Create a new issue on the main repository (not WG)
  • Create a new pull request from WG or user repository
    • Target desired branch (3.x, 4.x, etc.)
    • Reference Issue in pull request description
  • Get pull request reviewed by appropriate chapter committee(s) before first vote
  • After passing votes, Editor clicks “merge” button (hopefully)

​

https://github.com/mpi-forum/mpi-issues/wiki/Working-Group-Guidelines

12 of 29

Proposal Workflow: current branch

3.x branch

MPI 3.0

MPI 3.1

MPI 3.2

Pull request (for 3.2):

MPI_TYPE_GET_EXTENT is defined via deprecated features

13 of 29

Proposal Workflow: next branch

3.x branch

4.x branch

MPI 3.0

MPI 3.1

Pull request:

Fault Tolerance (for MPI-4)

Branch does not exist yet

Where to base the pull request?

14 of 29

Proposal Workflow: next branch

3.x branch

4.x branch

MPI 3.0

MPI 3.1

Pull request:

Fault Tolerance (for MPI-4)

Branch does not exist yet

Until 4.x branch exists,

base it against 3.x branch

15 of 29

Proposal Workflow: next branch

3.x branch

4.x branch

MPI 3.0

MPI 3.1

Pull request:

Fault Tolerance (for MPI-4)

When 4.x branch is created,

rebase the pull request to 4.x branch

16 of 29

Proposal Workflow: current branch, when next branch already exists

3.x branch

4.x branch

MPI 3.0

MPI 3.1

MPI 3.2

Pull request:

Datatype support functionality (for MPI-3.2)

Merge down to 4.x branch

when PR merged to 3.x branch

17 of 29

Working Group workflows: general

mpi-forum

Github organization

​

​

​

​

​

​

​

​

​

Chapter authors, editors have write access to private repos

mpi-standard

Git repo

[Private]

mpi-issues

Git repo

[Public]

mpiwg-tools

Github organization

​

​

​

​

​

​

​

​

​

Working group members have write access to private repos

mpi-standard

Git repo

[Private]

Fork

jdinan

user

​

​

​

​

​

​

​

​

​

​

​

​

mpi-standard

Git repo

[Private]

Fork

Pull Request

Pull Request

Pull Request

18 of 29

Working Group workflow: option 1

mpi-forum

Github organization

​

​

​

​

​

​

​

​

​

​

​

​

mpi-standard

Git repo

​

​

​

​

​

​

​

​

​

​

mpiwg-ft

Github organization

​

​

​

​

​

​

​

​

​

​

​

​

mpi-standard

Git repo

​

​

​

​

​

​

​

​

​

​

Pull Request

mpi-3.x

branch

mpi-3.x

branch

ticket

branch

Sync from Forum to WG

19 of 29

Working Group workflow: option 2

mpi-forum

Github organization

​

​

​

​

​

​

​

​

​

​

​

​

mpi-standard

Git repo

​

​

​

​

​

​

​

​

​

​

mpiwg-tools

Github organization

​

​

​

​

​

​

​

​

​

​

​

​

mpi-standard

Git repo

​

​

​

​

​

​

​

​

​

​

Pull Request

integration

branch

ticket

branch

mpi-3.x

branch

mpi-3.x branch

Sync from Forum to WG

20 of 29

Other Notes

  • Preserved SVN history for MPI-3.0 / MPI-3.1
    • Did not preserve SVN commit history for prior versions -- just saved the final state of each document
  • Tickets will be moved manually (by authors) from Trac
    • Use this opportunity to purge old tickets that are not active
  • Trac will remain available in read-only state for historical reference

21 of 29

Demonstration: Simple pull request

High level steps for a pull request:

​

  1. Create an mpi-forum/mpi-issues issue
  2. Fork the mpi-forum/mpi-standard repo (once)
  3. Clone your repo to your work machine (once)
  4. Make a branch in your clone
  5. Make and commit your edits to the branch
  6. Push your branch to your GitHub fork
  7. Create the pull request

mpi-forum / mpi-issues repo

mpi-forum / mpi-standard repo

Public issue

22 of 29

Demonstration: Simple pull request

High level steps for a pull request:

​

  • Create an mpi-forum/mpi-issues issue
  • Fork the mpi-forum/mpi-standard repo (once)
  • Clone your repo to your work machine (once)
  • Make a branch in your clone
  • Make and commit your edits to the branch
  • Push your branch to your GitHub fork
  • Create the pull request

mpi-forum / mpi-standard repo

jsquyres / mpi-standard repo

Fork

23 of 29

Demonstration: Simple pull request

High level steps for a pull request:

​

  • Create an mpi-forum/mpi-issues issue
  • Fork the mpi-forum/mpi-standard repo (once)
  • Clone your repo to your work machine (once)
  • Make a branch in your clone
  • Make and commit your edits to the branch
  • Push your branch to your GitHub fork
  • Create the pull request

jsquyres / mpi-standard repo

mpi-standard repo

Clone

24 of 29

Demonstration: Simple pull request

High level steps for a pull request:

​

  • Create an mpi-forum/mpi-issues issue
  • Fork the mpi-forum/mpi-standard repo (once)
  • Clone your repo to your work machine (once)
  • Make a branch in your clone
  • Make and commit your edits to the branch
  • Push your branch to your GitHub fork
  • Create the pull request

mpi-standard repo

​

​

​

​

​

​

​

mpi-3.x branch

my-changes branch

25 of 29

Demonstration: Simple pull request

High level steps for a pull request:

​

  • Create an mpi-forum/mpi-issues issue
  • Fork the mpi-forum/mpi-standard repo (once)
  • Clone your repo to your work machine (once)
  • Make a branch in your clone
  • Make and commit your edits to the branch
  • Push your branch to your GitHub fork
  • Create the pull request

mpi-standard repo

​

​

​

​

​

​

​

mpi-3.x branch

my-changes branch

26 of 29

Demonstration: Simple pull request

High level steps for a pull request:

​

  • Create an mpi-forum/mpi-issues issue
  • Fork the mpi-forum/mpi-standard repo (once)
  • Clone your repo to your work machine (once)
  • Make a branch in your clone
  • Make and commit your edits to the branch
  • Push your branch to your GitHub fork
  • Create the pull request

jsquyres / mpi-standard repo

​

​

​

​

​

​

mpi-standard repo

​

​

​

​

​

​

​

Push

my-changes branch

my-changes branch

27 of 29

Demonstration: Simple pull request

High level steps for a pull request:

​

  • Create an mpi-forum/mpi-issues issue
  • Fork the mpi-forum/mpi-standard repo (once)
  • Clone your repo to your work machine (once)
  • Make a branch in your clone
  • Make and commit your edits to the branch
  • Push your branch to your GitHub fork
  • Create the pull request

mpi-forum / mpi-standard repo

​

​

​

​

​

​

jsquyres / mpi-standard repo

​

​

​

​

​

​

Pull request

my-changes branch

mpi-3.x

branch

28 of 29

Demonstration

29 of 29

RTFW (Read the Fine Wiki)

​

  • Getting started with Git
  • Getting started with GitHub
  • Workflows
    • Filing an issue (“ticket”)
    • Filing a pull request
  • Migrating from SVN / Trac