Git development workflow (intermediate)

[ahmadia]

This is mostly fleshed out except for the section on committing at the bottom.

[wking]

On Sun, Apr 27, 2014 at 08:04:32PM -0700, Aron Ahmadia wrote:

• Merge in changes to Git intermediate lesson

The bookmark analogy is nice to underline the distinction between
commits (journal pages) and branches (bookmarks). However, it clouds
the directed-acyclic-graph nature of the commit history (where the
“branch” analogy works a bit better). To avoid the overhead of
keeping multiple models for the same Git concepts, I'd try and stick
to branchy analogies, and just switch over briefly to alternative
analogies to clarify confusing points. In this case, I think the
pointer updates are more clearly demonstrated graphically, with
something like 'git log --graph --decorate' (or the Pro Git figures
1) to show the updates between commits.

[wking]

I see Git usage breaking down into a few layers:

• Creating commits (staging, add, rm, commit, checkout)
• Inspection (status, diff, log)
• Branched development (branch, merge, rebase, checkout)
• Remotes (push, pull, fetch, remote-tracking branches)

You need a bit of mixing (e.g. push and pull before really talking
about branching) to keep folks interested, but I think it's less
confusing if we can keep these layers as separate as possible. As it
stands, it doesn't look like you talk about branch integration
(merge/rebase/pull-requests):

$ git show origin/pr/467 | grep -i '$ git|request|merge|rebase|pull'
Merge in changes to Git intermediate lesson
+$ git checkout master
+$ git checkout -b pipeline_fix
+$ git branch -v
+$ git status
+$ git status
+$ git status
+$ git diff
+$ git add documentation.txt
+$ git status
+$ git add python_pipeline.ipy
+$ git status
+$ git diff
+$ git diff --staged
+$ git reset python_pipeline.ipy
+$ git status

and the branch flow you start out discussing gets lost in a discussion
of the staging area. I think it would stay more focused and easy to
understand if each of your goals (branched development, staging,
diffs, …) got its own notebook.

[ahmadia]

@wking - I find branches to be the singularly most incompletely misunderstood topic for people who are new to Git. Your feedback is appreciated here.

I agree that the branch discussion is getting lost. I'll start with staging, then go to branches, then commits.

[ahmadia]

My plan is to complete the notebooks as originally outlined (there's one more left for remotes, pull requests, and merging), then refactor if needed.

[wking]

On Mon, Apr 28, 2014 at 11:14:35AM -0700, Aron Ahmadia wrote:

I agree that the branch discussion is getting lost. I'll start with
staging, then go to branches, then commits.

Maybe I'm missunderstanding your wording here, but I think branches
are only understandable once you have a solid grasp of what a commit
is. The whole staging thing is useful for polishing commits, but not
critical, so you can bump that back, but I'd keep commits in front
of branches.

[ahmadia]

@wking - The previous notebook in this series goes into commits in detail. I argue that you don't need to understand how to make a commit to understand how to use a branch to point to one.

[wking]

On Mon, Apr 28, 2014 at 11:16:35AM -0700, Aron Ahmadia wrote:

My plan is to complete the notebooks as originally outlined (there's
one more left for remotes, pull requests, and merging), then
refactor if needed.

Sounds like a plan :). It's easier to put the puzzle together once
all the pieces are layed out on the table.

[wking]

On Mon, Apr 28, 2014 at 11:17:51AM -0700, Aron Ahmadia wrote:

The previous notebook in this series goes into commits in detail. I
argue that you don't need to understand how to make a commit to
understand how to use a branch to point to one.

No, but you don't want people thinking, “What was a commit again? Oh
yeah, a snapshot of my code, with pointers to parent commits and an
explanatory message. Oh wait, what did the instructor just say?”.
You want them to be thinking, “Ah, my old friend the commit. I know
all about you. I could make thousands of these things, and I'll need
some way to keep those thousands organized. Branches? That sounds
like just the ticket.”

[ChristinaLK]

Random interjection: I don't know if this is helpful or not, but I often think of branch pointers as paperweights. If each branch is a pile of commits on your desk, then the branch pointer is a paperweight on top of each one.

@ahmadia , I'd be interested in helping write/edit/what-have-you the intermediate lesson in remotes, let me know if I can help out.

[ahmadia]

@ChristinaLK - I'd love to have your help! I'll ping back when I've got more notes down.

[wking]

On Mon, May 05, 2014 at 02:35:33PM -0700, ChristinaLK wrote:

Random interjection: I don't know if this is helpful or not, but I often think of branch pointers as paperweights. If each branch is a pile of commits on your desk, then the branch pointer is a paperweight on top of each one.

Both this and the bookmark example work well for serial commits, but make branching and merging difficult to explain. I've been trying to think of a simple physical parallel for folks that like to learn through a tactile experience. Maybe index card commits with smaller branch/tag markers?

If I was doing this in class, I'd have folks fill in actual commit messages. I'd probably want a HEAD marker too.

This would work well if you could get everyone around a single table. If you needed something to wave around at the front of the class, maybe hole-punching the index cards and stringing them together instead of overlapping the cards themselves? You could merge the new-ui branch into master with a bit of wiggling to get the to-be-merged commits closer, but anything more complicated than that would be hard to render in index cards.

I'm not sure it adds much on top of nice graphical representations, but who knows :p.

[ahmadia]

I still like bookmarks in a logbook. There's the concept of naturally
progressing forward, and "keeping track" of progress. It's not a surprise
that Mercurial (which has much better thought-out metaphors), call these
things bookmarks :)

On Mon, May 5, 2014 at 5:23 PM, W. Trevor King [email protected]:

On Mon, May 05, 2014 at 02:35:33PM -0700, ChristinaLK wrote:

Random interjection: I don't know if this is helpful or not, but I often
think of branch pointers as paperweights. If each branch is a pile of
commits on your desk, then the branch pointer is a paperweight on top of
each one.

Both this and the bookmark example work well for serial commits, but make
branching and merging difficult to explain. I've been trying to think of a
simple physical parallel for folks that like to learn through a tactile
experience. Maybe index card commits with smaller branch/tag markers?

[image: index-branch-small]https://cloud.githubusercontent.com/assets/209920/2883993/54d379a6-d4a3-11e3-8103-60bbc2c2b1b3.jpg

If I was doing this in class, I'd have folks fill in actual commit
messages. I'd probably want a HEAD marker too.

This would work well if you could get everyone around a single table. If
you needed something to wave around at the front of the class, maybe
hole-punching the index cards and stringing them together instead of
overlapping the cards themselves? You could merge the new-ui branch into
master with a bit of wiggling to get the to-be-merged commits closer, but
anything more complicated than that would be hard to render in index cards.

I'm not sure it adds much on top of nice graphical representations, but
who knows :p.

—
Reply to this email directly or view it on GitHubhttps://github.com//pull/467#issuecomment-42248092
.

[ChristinaLK]

Ha, I've thought about doing something similar with index cards! I think that's great as a teaching strategy, but doesn't help so much with written lessons.

I think my only problem with the bookmark metaphor is that books are, usually, linear. I suppose if you really wanted to go crazy, you could say you were reading a "choose your own adventure" and want to track the multiple story paths with multiple bookmarks. But I think what you have is already about as good as it's going to get.

A+ software: call things by perfect metaphorical names. ;)

[wking]

On Mon, May 05, 2014 at 03:28:27PM -0700, Aron Ahmadia wrote:

I still like bookmarks in a logbook. There's the concept of
naturally progressing forward, and "keeping track" of progress.
It's not a surprise that Mercurial (which has much better
thought-out metaphors), call these things bookmarks :)

But branch and merge points are harder to explain with a book
metaphor, since pages in a book are usually serial. Hmm. Unless you
map branches to x/y locations on each page (conserved across pages)
and start ripping out parts of pages that are on branches that don't
inherit a particular commit. Looking at pages in the closed book:

| | | | | | | | | | <-- master
| | | | | | | <-- new-ui
1 2 3 4 5 6 7 8 9 a b c d

Which translates to:

1---2---3---4---5---6---7---b---c---d master
\ /
8---9---a---- new-ui

I'm still not sure how you'd represent the merge at b, since b isn't
part of the new-ui branch.

[ethanwhite]

There's a lot of good material here and since things have stalled I'd recommend dealing the conflicts, merging this in, and building on the material from there.

[gvwilson]

+1 to resolving conflicts and merging this before #759.

[ahmadia]

I can take a crack at updating this tomorrow.