pages tagged projectyakkinghttp://yakking.branchable.com/tags/project/yakkingikiwiki2017-04-05T11:00:12ZNew 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>
Getting started with a projecthttp://yakking.branchable.com/posts/getting-started/Daniel Silverstone2016-04-27T11:00:15Z2016-04-27T11:00:08Z
<p>I've talked <a href="http://yakking.branchable.com/posts/research-before-coding/">before</a> about the <a href="http://yakking.branchable.com/posts/truism-1-if-you-dont-know-why/">sorts of things</a> you should know
<a href="http://yakking.branchable.com/posts/truism-2-if-you-dont-have-a-plan/">before you get started</a> writing some code. I've even touched on
<a href="http://yakking.branchable.com/posts/source-tree-organisation/">typical filesystem layouts</a> for projects. And we've talked a little
about <a href="http://yakking.branchable.com/posts/software-freedom-concepts/">free software licences</a> and even a bit about <a href="http://yakking.branchable.com/posts/mensch/">being a mensch</a>.</p>
<p>This week I'd like to talk to you a little bit about getting started with a
project from the point of view of the more social side of things. It's not
often that we start projects with the explicit intention of growing a community
immediately, and oftentimes we end up with a community without even really
planning it. Thanks to the wonders of the general F/LOSS community, these can
sometimes go entirely without hitch; yet sometimes really awful things happen
(and no, I'm not going to link to them) and people can end up feeling
marginalised, unwanted, or even downright attacked.</p>
<p>I am grateful, on a more than daily basis, that despite being fat, ginger, and
gay, I am an able-bodied cis white male and as such I get so much privilege in our
communities that I am rarely directly attacked. I try, again on a more than
daily basis, to check my privilege and behave in a courteous way. I often
fail, and I hope that by acknowledging that I am at least a little better than
those who fail and ignore it. I run, or participate in, a significant number
of projects. Some have <a href="https://www.debian.org/social_contract">social contracts</a> and <a href="https://www.debian.org/code_of_conduct">codes of conduct</a> such as
<a href="https://www.debian.org/">Debian</a>, and others simply rely on the community members being "nice" to one
another.</p>
<p>I have, recently, been considering a code of conduct, or social contract, for
my <a href="https://www.gitano.org.uk/">Gitano</a> group of projects; and also I have been considering it in a wider
context of my membership in the <a href="http://www.netsurf-browser.org/">NetSurf</a> project and in my barely new-born
participation in the <a href="http://kicad-pcb.org/">KiCad</a> project. In my bimbling around, I have
encountered numerous options for codes of conduct or social contracts and have
whittled my selection set down to <a href="http://citizencodeofconduct.org/">The citizen code of conduct</a>,
<a href="http://contributor-covenant.org/version/1/4/">The contributor covenant</a>, and <a href="http://todogroup.org/opencodeofconduct/">The open code of conduct</a>.</p>
<p>I'm not yet sure which one I'll pick, or if I feel the need to produce my own
variant of an existing one. (A good friend reminded me that codes of conduct,
or social contracts / covenants are kinda like cryptography -- necessary, but
don't go rolling your own unless you're especially skilled in the domain. So
if you feel the need to have a different CoC, amend an existing one and
remember to <em>feed back</em> to the original authors, just like you would with
code). However, one thing I'm sure of is that the next time I start a new
project, right alongside the <code>README</code> and the <code>LICENCE</code>/<code>COPYING</code> file, there's
going to be a <code>CONDUCT</code> file (or something of similar name) with the relevant
covenant or code of conduct in it.</p>
<p>Perhaps next time you start a project, just after you've run <code>git init</code> and
just before you <code>git commit</code> your chosen F/LOSS licence, perhaps you too will
add a contributor covenant or code of conduct to shape your future community
just a little better than it might self-organise otherwise.</p>
Bus Factorhttp://yakking.branchable.com/posts/bus-factor/Daniel Silverstone2015-07-15T11:00:12Z2015-07-15T11:00:06Z
<blockquote><p>I decided that I would write this article one lunchtime, but by the time
evening had come around, I had completely forgotten the topic of the article
I had intended to write. Fortunately Richard had been at lunch with me and
he could remind me that I was to write about <em>Bus Factor</em> -- I can't think of
a single better example of why this is important to do.</p></blockquote>
<p><a href="http://en.wikipedia.org/wiki/Bus_factor">Bus factor</a> is, quite simply, the number of people who need to become
<em>"indisposed"</em> before a project will falter. As the linked Wikipedia article
says, it is a measure of the concentration of critical information in a
project.</p>
<p>We encounter the issues of <em>bus factor</em> almost every day when we learn
something unique in our day-to-day work. As information workers, the
generation of unique knowledge is our bread-and-butter and we need ways to
ensure that the knowledge we create is not lost if we are. We do this by way
of writing things down, telling them to others, putting them in
<a href="http://en.wikipedia.org/wiki/Knowledge_management">knowledge-management</a> systems and any other thing we can do to ensure that
the knowledge is safe.</p>
<p>As software engineers we do this a lot of the time by committing our new
knowledge as source code to a revision control system and pushing it elsewhere.
Of course, we then sometimes don't improve the bus-factor but instead create
a <a href="http://en.wikipedia.org/wiki/Single_point_of_failure">single-point-of-failure</a> for the hardware infrastructure we depend upon.</p>
<p>What's more, as knowledge workers, we have two conflicting desires at the root
of our pursuit of knowledge. We like to know things that others do not know
since that gives us a measure of smugness or superiority. We enjoy learning
new things but above all that we enjoy <em>inventing</em> new things and holding those
precious nuggets of joy to ourselves for a short while. Conflicting with this
desire is the desire to be seen to be clever/wonderful/inventing new things.
Fortunately that second desire is the one which reduces the <em>bus factor</em> for
the new knowledge and it is to this second desire that we must adhere.</p>
<p>When software projects begin, typically they begin with one person having a
clever idea. That project intrinsically begins with a <em>bus factor</em> of one.
Hopefully, if the project gains users, the project will gain further developers
and in doing so will reduce its bus factor providing the developers share
knowledge and understanding rather than segmenting the project and never
encroaching on one another's domain. Fortunately F/LOSS projects tend to be
run in a way which encourages the sharing. So if you start a project, please
make sure you write stuff down and do your best to get at least one other
person involved, ideally <em>before</em> you have users depending on you.</p>
<p>After all, it could be <strong>you</strong> who goes <em>under a bus</em> tomorrow.</p>