[mpiwg-tools] Changes from Bordeaux to MPIR

[Jeff Squyres (jsquyres)]

On Oct 9, 2015, at 1:24 AM, Marc-Andre Hermanns <hermanns at jara.rwth-aachen.de> wrote:
> 
> Hi Jeff,
> 
> (CC: Wes, to keep him in the loop for process/convention finding)
> 
> thanks for the updates to the MPIR texts. As this being the first pull
> request I work on, I have some questions:
> 
> 1) The pull request states it wants to merge into the
> 'mpiwg-tools:mpir-1.x' branch. But don't we need a separate branch in
> our fork, to enable the "final pull-request" into the mpi-forum:mpir
> document? If we directly pull changes into our main branch of the
> fork, how can we have separate pull requests for separate
> issues/tickets that the forum has/wants to vote on?

It's common to make a new branch for every pull request that you file.

More specifically: it's a common Github newbie mistake to *not* make a separate branch for every PR.

Consider: a PR is a request to pull in a bunch of commits to the target branch.  How do you specify *which* commits that you want to be pulled?  You make a branch.  *All* the commits on that branch -- i.e., all the commits from the point where the branch was made to the tip of that branch -- are part of the PR.  Github is even smart enough such that *if you change the branch while the PR is open, the commits listed on the PR will automatically update*.  E.g., if you add more commits.  Or you rebase.  Or you squash commits.  Or rewrite the branch to have entirely new commits (vs. when you first created the PR).  ...and so on.

Hence, the branch I made is in *my* fork of the mpir repo.  If/when my PR is accepted (i.e., merged in), my commits will show up in the mpir repo on the mpir-1.x branch.

Make sense?

(pro tip: start thinking about git as a graph, in the computer science sense of the word -- then git will start making a *lot* more sense)

> 2) As commented on the pull request at:
> 
> https://github.com/mpiwg-tools/mpir/pull/1
> 
> we discussed some wording that goes beyond what this current pull
> requests reflects. Should we update the pull request, or merge it and
> create a new branch for further updates?

Yeah, sorry about that -- I had to miss yesterday's call.

We have two options:

1. Anh can file an entirely new PR that obsoletes mine, and we can close mine.

2. Anh can file a pull request against jsquyres:pr/mpir-being-debugged-fixes.  I can accept his changes, which will then merge his changes into my branch, which will automatically update the existing PR.

Either is fine.

(#2 may sound mind blowing to those of you to whom this is a new concept, but it's actually quite common -- i.e., you're effectively filing a PR against a PR, and it works exactly as you would expect it to)

> 3) In the call yesterday, we were all Git novices, thus I am not sure
> whether we agreed on the right workflow within the working group. Our
> idea was to create a branch on the working-group repo of the document,
> and commit to there, so multiple people can access the text from
> there, and we can also create the pull request to the mpi-forum from
> there.

No, let's not do that.

> Would one still need "personal forks" of the documents?

Yes.  This is a much better practice.

> I could
> imagine to pull from personal forks into the created branch instead of
> working on the branch directly. Is that better practice?

Yes.  This is pretty much The Github Way: individual people create forks and then file pull requests against the upstream repo (e.g., in our case, the mpiwg-tools/mpir repo, and then ultimately the mpi-forum/mpir repo).

There is a bit of a new ground for us to figure out, though: since WGs now have their own "private" working areas to create their own text, etc., when exactly do we file a PR against our own WG repo and when do we file a PR against the mpi-forum repo?  (I think Marc-Andre asked the same question)  I don't have an immediate answer for this.

> 4) If 3 makes sense, how can I merge Jeffs pull request not into the
> main branch of mpiwg-tools:mpir but into something like
> mpiwg-tools:issue_6_being_debugged?

No.  Once a PR has been created, the source and target repo:branches are fixed.  If you want to change the source/target, you have to close that PR and open a new one.

-- 
Jeff Squyres
jsquyres at cisco.com
For corporate legal information go to: http://www.cisco.com/web/about/doing_business/legal/cri/