<html>
<head>
<meta http-equiv="content-type" content="text/html; charset=ISO-8859-1">
</head>
<body bgcolor="#FFFFFF" text="#000000">
<div markdown-here-wrapper-content-modified="true" style=""
data-md-original="I%20feel%20like%20git%20workflow%20is%20a%20subject%20that%20keeps%20coming%20up%20piecemeal.%C2%A0%20Our%20current%20workflow%20just%20gave%20me%20a%20paper%20cut%20(I%20had%20to%20spend%20a%20few%20minutes%20puzzling%20over%20the%20output%20of%20different%20git%20tools%20to%20reconcile%20them)%2C%20so%20if%20you'll%20indulge%20me%2C%20I'd%20like%20to%20take%20this%20one%20opportunity%20to%20explain%20where%20I'm%20coming%20from.%C2%A0%20I%20promise%20I'll%20only%20do%20this%20once.%C2%A0%20If%20our%20workflow%20stays%20as%20it%20is%2C%20I'm%20cool%20with%20that%2C%20but%20I%20feel%20like%20there's%20room%20for%20improvement.%3Cbr%3E%3Cbr%3EI%20was%20just%20reviewing%20a%20branch%20for%20Tom.%C2%A0%20Since%20this%20was%20my%20second%20pass%20on%20it%2C%20I%20went%20to%20the%20git%20log%20to%20see%20what%20changed%20since%20my%20last%20pass.%C2%A0%20I've%20attached%20a%20screenshot%20of%20what%20magit%20showed%20me.%C2%A0%20The%20complicated%20history%20tree%20made%2
0it%20challenging%20to%20find%20all%20the%20relevant%20revisions.%C2%A0%20Tom%20described%20making%20several%20changes%20that%20I%20didn't%20see%20at%20first%2C%20until%20I%20found%201881da32%20and%20friends%20near%20the%20bottom%20of%20the%20screen.%3Cbr%3E%3Cbr%3EOur%20git%20history%20frequently%20looks%20like%20this%2C%20especially%20near%20the%20end%20of%20a%20sprint%2C%20because%20when%20we're%20working%20on%20a%20feature%20branch%2C%20we%20merge%20its%20parent%20(usually%20master)%20back%20into%20it%20so%20regularly.%C2%A0%20Isolating%20feature%20work%20into%20a%20branch%20is%20great%2C%20but%20we%20lose%20some%20of%20the%20utility%20of%20having%20that%20isolation%2C%20of%20having%20a%20single%20stream%20of%20commits%20about%20the%20feature%2C%20when%20we%20merge%20the%20parent%20back%20in%20so%20often.%3Cbr%3E%3Cbr%3EI%20like%20referring%20back%20to%20version%20control%20logs%2C%20probably%20more%20than%20most.%C2%A0%20To%20me%2C%20it's%20documentation.%C2%A0%20It's%20that%20sp
ecial%20kind%20of%20documentation%20that%20you%20*must*%20write%20*while*%20you're%20doing%20the%20work.%C2%A0%20Understanding%20what%20motivated%20a%20previous%20change%20often%20helps%20me%20do%20better%20when%20I'm%20working%20on%20the%20next%20one.%C2%A0%20For%20example%2C%20if%20the%20log%20explains%20how%20a%20commit%20fixes%20a%20subtle%20bug%2C%20I%20can%20avoid%20reintroducing%20that%20bug%20later%20on.%3Cbr%3E%3Cbr%3EBecause%20I%20think%20of%20it%20like%20documentation%2C%20I%20feel%20like%20it's%20worth%20putting%20a%20little%20extra%20effort%20into%20making%20the%20history%20nice.%C2%A0%20Yes%2C%20improving%20our%20workflow%20here%20might%20require%20more%20effort%20than%20our%20current%20merge-heavy%20system.%C2%A0%20But%20like%20any%20effort%20put%20into%20documentation%2C%20I%20trust%20that%20it%20will%20pay%20dividends%20in%20the%20future.%C2%A0%20I%20don't%20think%20it's%20merely%20putting%20effort%20into%20git%20for%20the%20effort's%20sake.%3Cbr%3E%3Cbr%3EThere%20are
%20at%20least%20two%20workflow%20changes%20we%20could%20make%20that%20would%20improve%20our%20history-documentation%3A%3Cbr%3E%3Cbr%3E1.%20Just%20stop%20merging%20the%20parent%20branch%20back%20into%20its%20parent%20so%20regularly.%C2%A0%20%60git%20diff%20master...%60%20would%20be%20the%20canonical%20way%20to%20review.%C2%A0%20When%20the%20feature%20branch%20gets%20merged%20into%20master%2C%20the%20merge%20would%20be%20larger%2C%20so%20we'd%20have%20to%20put%20in%20additional%20effort%20to%20make%20sure%20that%20goes%20smoothly%20and%20doesn't%20introduce%20bugs.%3Cbr%3E2.%20If%20we%20don't%20like%20big%20merges%20(very%20understandable!)%2C%20where%20we%20currently%20merge%20the%20parent%20back%20into%20feature%20branches%2C%20instead%20we%20could%20rebase%20the%20feature%20branch%20on%20top%20of%20its%20parent.%C2%A0%20To%20do%20this%2C%20we'll%20have%20to%20let%20ourselves%20rewrite%20history%20on%20git.curoverse.com.%C2%A0%20This%20would%20require%20more%20discipline%20from%20us%2
C%20but%20I%20feel%20like%20we%20already%20have%20that%2C%20since%20our%20rule%20is%20that%20a%20developer%20owns%20the%20branch%20they%20make.%C2%A0%20When%20you%20pull%20someone%20else's%20feature%20branch%20for%20review%2C%20you'd%20use%20%60git%20pull%20-f%60%20to%20get%20the%20rewritten%20history.%C2%A0%20Our%20process%20for%20reviewing%20and%20merging%20feature%20branches%20would%20remain%20the%20same%2C%20and%20those%20merges%20should%20be%20as%20straightforward%20as%20they%20are%20today.%3Cbr%3E%3Cbr%3EThere%20might%20be%20other%20options%20too%2C%20but%20I%20think%20these%20would%20require%20the%20least%20disruption%20to%20our%20current%20workflow.%C2%A0%20Which%20is%20my%20goal%2C%20because%20I%20generally%20like%20our%20current%20workflow.%C2%A0%20I%20just%20wish%20I%20could%20understand%20what's%20happened%20when%20I%20look%20at%20the%20history.%C2%A0%20%3A)%3Cbr%3E%3Cbr%3EThanks%20for%20reading%2C%3Cbr%3E%3Cbr%3E"
class="markdown-here-wrapper" data-md-url="null"
id="markdown-here-wrapper-391612">
<p style="margin: 1.2em 0px ! important;">I feel like git workflow
is a subject that keeps coming up piecemeal. Our current
workflow just gave me a paper cut (I had to spend a few minutes
puzzling over the output of different git tools to reconcile
them), so if you’ll indulge me, I’d like to take this one
opportunity to explain where I’m coming from. I promise I’ll
only do this once. If our workflow stays as it is, I’m cool with
that, but I feel like there’s room for improvement.</p>
<p style="margin: 1.2em 0px ! important;">I was just reviewing a
branch for Tom. Since this was my second pass on it, I went to
the git log to see what changed since my last pass. I’ve
attached the log graph output magit showed me. The complicated
history tree made it challenging to find all the relevant
revisions. Tom described making several changes that I didn’t
see at first, until I found 1881da32 and friends near the bottom
of the screen.</p>
<p style="margin: 1.2em 0px ! important;">Our git history
frequently looks like this, especially near the end of a sprint,
because when we’re working on a feature branch, we merge its
parent (usually master) back into it so regularly. Isolating
feature work into a branch is great, but we lose some of the
utility of having that isolation, of having a single stream of
commits about the feature, when we merge the parent back in so
often.</p>
<p style="margin: 1.2em 0px ! important;">I like referring back to
version control logs, probably more than most. To me, it’s
documentation. It’s that special kind of documentation that you
<em>must</em> write <em>while</em> you’re doing the work.
Understanding what motivated a previous change often helps me do
better when I’m working on the next one. For example, if the log
explains how a commit fixes a subtle bug, I can avoid
reintroducing that bug later on.</p>
<p style="margin: 1.2em 0px ! important;">Because I think of it
like documentation, I feel like it’s worth putting a little
extra effort into making the history nice. Yes, improving our
workflow here might require more effort than our current
merge-heavy system. But like any effort put into documentation,
I trust that it will pay dividends in the future. I don’t think
it’s merely putting effort into git for the effort’s sake.</p>
<p style="margin: 1.2em 0px ! important;">There are at least two
workflow changes we could make that would improve our
history-documentation:</p>
<ol style="margin: 1.2em 0px;padding-left: 2em;">
<li style="margin: 0.5em 0px;">Just stop merging the parent
branch back into its parent so regularly. <code
style="font-size: 0.85em; font-family:
Consolas,Inconsolata,Courier,monospace;margin: 0px 0.15em;
padding: 0px 0.3em; white-space: pre-wrap; border: 1px solid
rgb(234, 234, 234); background-color: rgb(248, 248, 248);
border-radius: 3px 3px 3px 3px; display: inline;">git diff
master...</code> would be the canonical way to review. When
the feature branch gets merged into master, the merge would be
larger, so we’d have to put in additional effort to make sure
that goes smoothly and doesn’t introduce bugs.</li>
<li style="margin: 0.5em 0px;">If we don’t like big merges (very
understandable!), where we currently merge the parent back
into feature branches, instead we could rebase the feature
branch on top of its parent. To do this, we’ll have to let
ourselves rewrite history on git.curoverse.com. This would
require more discipline from us, but I feel like we already
have that, since our rule is that a developer owns the branch
they make. When you pull someone else’s feature branch for
review, you’d use <code style="font-size: 0.85em;
font-family: Consolas,Inconsolata,Courier,monospace;margin:
0px 0.15em; padding: 0px 0.3em; white-space: pre-wrap;
border: 1px solid rgb(234, 234, 234); background-color:
rgb(248, 248, 248); border-radius: 3px 3px 3px 3px; display:
inline;">git pull -f</code> to get the rewritten history.
Our process for reviewing and merging feature branches would
remain the same, and those merges should be as straightforward
as they are today.</li>
</ol>
<p style="margin: 1.2em 0px ! important;">There might be other
options too, but I think these would require the least
disruption to our current workflow. Which is my goal, because I
generally like our current workflow. I just wish I could
understand the history better. :)</p>
<p style="margin: 1.2em 0px ! important;">Thanks for reading,</p>
</div>
<div class="moz-signature markdown-here-signature">-- <br>
Brett Smith</div>
</body>
</html>