pages tagged workflowyakkinghttp://yakking.branchable.com/tags/workflow/yakkingikiwiki2018-03-07T12:03:12ZCycles in developmenthttp://yakking.branchable.com/posts/cycles/Lars Wirzenius2018-03-07T12:03:12Z2018-03-07T12:03:07Z
<p>Software development tends to happen in cycles and it's good to be
aware of this.</p>
<p>The innermost cycle is the edit-build-test-debug loop. You write or
change some code, you build the software (assuming a compiled
language), and you run the software to test it, either manually or by
using automated tests.</p>
<p>Being the innermost cycle, it's probably where most of development
time happens. It tends to pay to optimise it to make it as fast as
possible. Each of the parts can be optimised. For editing, use an
editor you like and are comforable with. Also, a keyboard you can type
efficiently with. For building, use incremental building, and maybe
turn off optimisation to make the build got faster. For testing, maybe
run only the relevant tests, and make those run quickly.</p>
<p>Other cycles are:</p>
<ul>
<li><p>The TDD cycle: add a new test, add or change code to make test pass,
refactor. This tends to embed the edit-build-test-debug loop.
Usually at most minutes in length.</p></li>
<li><p>Adding a minimal user-visible change: a new feature is broken into
the smallest increment that makes the user's life better, and this
is then developed, often using a number of TDD cycles.</p></li>
<li><p>A "sprint" in Agile development: often a week or two or three, often
adds an entire user-visible feature or other change, or several.</p></li>
<li><p>A release cycle: often many weeks or months, adds significant new
features. The set of added features or other changes, and the length
of the release cycle are all often determined by business interests,
business strategy, and often ridiculed by developers. This sometimes
happens for open source projects too, however. For example, a Linux
distribution might synchronise its own release schedule with
multiple major, critical components it includes.</p></li>
<li><p>The maintenance cycle: after the software has been "finished", and
put into production, bugs and other misfeatures get fixed and once
there's enough of them, a new release is made and put into production.</p></li>
</ul>
<p>In each case, it is useful to know the intended and expected length of
the cycle, and what needs to happen during the cycle, and what the
intended and expected result should be. It is also useful to try to
identify and remove unnecessary clutter from the cycles, to make
things go smoothly.</p>
The only proper git workflow, use nothing elsehttp://yakking.branchable.com/posts/git-workflow/Lars Wirzenius2018-02-21T12:00:17Z2018-02-21T12:00:11Z
<p>The title of this article is intentionally provocative.</p>
<p>Git is a flexible tool that allows many kinds of workflow for using
it. Here is the workflow I favour for teams:</p>
<ul>
<li><p>The <code>master</code> branch is meant to be always releasable.</p></li>
<li><p>Every commit in <code>master</code> MUST pass the full test suite, though not
all commits in merged change sets need to do that.</p></li>
<li><p>Changes are done in dedicated branches, which get merged to <code>master</code>
frequently - avoid long-lived branches, since they tend to result in
much effort having to be spent on resolving merge conflicts.</p>
<ul>
<li>If frequent merging is, for some reason, not an option, at least
rebase the branch onto current master frequently: at least
daily. This keeps conflicts fairly small.</li>
</ul>
</li>
<li><p>Before merging a branch into <code>master</code>, rebase it onto <code>master</code> and
resolve any conflicts - also rebase the branch so it tells a clean
story of the change.</p>
<ul>
<li><p><code>git rebase -i master</code> is a very powerful tool. Learn it.</p></li>
<li><p>A clean story doesn't have commits that fix mistakes earlier in
the branch-to-be-merged, and introduces changes within the
branch in chunks of a suitable size, and in an order that makes
sense to the reader. Clean up "Fix typo in previous commit" type
of commits.</p></li>
</ul>
</li>
<li><p>Update the <code>NEWS</code> file when merging into <code>master</code>. Also Debian
packaging files, if those are included in the source tree.</p></li>
<li><p>Tag releases using PGP signed, annotated tags. I use a tool called
<a href="http://git.liw.fi/bumper/">bumper</a>, which updates <code>NEWS</code>, <code>version.py</code>, <code>debian/changelog</code>,
tags a release, and updates the files again with with <code>+git</code>
appended to version number.</p>
<ul>
<li>Review, update <code>NEWS</code>, <code>debian/changelog</code> before running bumper
to make sure they're up to date.</li>
</ul>
</li>
<li><p>Name branches and tags with a prefix <code>foo/</code> where <code>foo</code> is your
username, handle, or other identifier.</p></li>
<li><p>If <code>master</code> is broken, fixing it has highest priority for the
project.</p></li>
<li><p>If there is a need for the project to support older releases, create
a branch for each such, when needed, starting from the release's
tag. Treat release branches as <code>master</code> for that release.</p></li>
</ul>
New project? Start with the scaffoldinghttp://yakking.branchable.com/posts/scaffolding/Lars Wirzenius2017-04-05T11:00:12Z2017-04-05T11:00:06Z
<p>So you're starting a new project. You have an idea for something, and
a vision for how to implement it. What should you do first?</p>
<p>If you're like me, you burn to start with the interesting coding bit
first. After a few hours of furious typing, you've done the fun bit,
and you need to add all the boring bits: automated tests (unless you
did TDD, and even then there may be missing tests), documentation, a
manual page, a README, perhaps packaging (Debian, RPM, language
specific), a CI project, a home page, etc. There's a lot of it. That
is usually when my enthusiasm fades. A lot of my projects end up as a
single file in <code>~/bin</code>.</p>
<p>I call the boring bits scaffolding, and I've learnt that it pays to do
them first. Not only is that often the only time I will actually do
them, but once the scaffolding is in place, the fun bits are also more
fun to do.</p>
<p>If I have unit and integration test frameworks in place, adding
another test is only a small incremental task. If I haven't got them
in place (particularly for integration tests), I tend to postpone
writing tests. No chance of TDD, whereas when I put in an integration
test framework, I often to TDD at the program level, not just at the
individual class and method level.</p>
<p>Likewise, if I start by writing a manual page, adding another sentence
or paragraph is easy. Also, writing a manual page, or any
documentation, clarifies my thinking about what the program should
actually do, and how it should be used. This makes writing the code
more pleasant.</p>
<p>Having CI in place from the beginning, means the tests I write get
exercised from the start. This finds bugs earlier, even if I run my
tests manually as well. CI never thinks "I can run test faster this
one time by taking this clever shortcut".</p>
<p>Of course, putting up a lot of scaffolding takes effort, and it's all
wasted if you don't actually want to write the program after all.
Sometimes what sounds like a brilliant idea on the last train home
from a party, makes no sense at all in the morning. (Personal
experience, ahem.)</p>
<p>Thus it may make sense to start with a simple proof of concept, or
prototype implementation to verify the soundness of you idea, then
throw that away, and set up scaffolding, before you start writing
production code.</p>
<p>My latest personal project has a manual page, unit and integration
tests, Debian packaging, a CI project, and a home page. I can install
it and run it. It does't yet do anything useful. Before all this, I
wrote a prototype to prove the idea I had, and threw that away. Some
time this year I will start dropping in modules to actually do useful
stuff, and that'll be easy, since I won't need to worry about all the
boring bits. As soon as it does anything useful, I can also point
friends at a Debian package and ask them to try my latest masterpiece.</p>
<p>What's more, I have a better chance of getting them to help by writing
a module they need themselves, since they just need to write the
module and don't need to worry about the rest.</p>