Tiny Capistrano Gotcha

I’m using Capistrano to automate a distributed environment. I love the tool, but one small thing that I see time and again with it: if a single node in a role cannot be reached, then executing commands on that node will fail.

 

It’s a bit of a bummer, but what’re you gonna do when it’s such a great tool otherwise?

Useful Bash date Command

Most every time I write a shell script with bash, I need a date in there somewhere. And most every time, I need to read the man page to work out what the heck the format is I like. Now it’s documented here:

date ‘+%b_%d_%H%M’

This outputs as Name Of Month_Today’s Date_The 24 hour clock time right now.

It’s useful to enclose in backticks:

df -h | mail -s “The disk usage at: `date ‘+%b_%d_%H%M’`” jam@jamandbees.net

 

 

 

What Is Good Documentation?

I’ve been thinking a lot for the last few days about technical documentation, the notes that we keep as developers.

I’m in the habit of keeping documentation for the current state of the system. That’s always seemed reasonable to me. Whatever version has just been released, that’s documented well and that has always seemed reasonable and good to me.

Now, though, I’m thinking about how when I’m handing a system over to someone else the documentation they want is how the system evolved during development. The “what happened in the past” part of this is captured in version control. The “why were these decisions made” part is not, and that’s a useful piece of the puzzle for anyone who has to maintain someone else’s codebase.

I document the “how to use this” for each stable release of a codebase. I have never written down the “Why I made this decision” bit of things. When I think of how many times I’ve worked on someone else’s piece of code and the details of why this is the implementation became clear because changes started revealing why they were good decisions to begin with, I’m led to wonder if documenting intent is a good idea.

 

Is this what the intention behind commit messages is? The code documents the code, the comments document the pieces of the code that are non-obvious, and the commit messages document the intention behind each change?

How to join an open source project

I’ve been wanting to sharpen my edge against an open source project recently. Specifically, my C++ edge.

As such, I’ve started working in on libreoffice. How I decided on libreoffice? I wanted a C++ project, and knew it was written in C++.

So, how did I get started? I went to the libreoffice website and there was a big link to the developers’ section on the front page. I followed the instructions there, downloaded the code, followed the instructions for building it, and then started looking for the bug list. Libreoffice has, very awesomely, a section on their developers’ site called Easy Hacks, which is where I started.

I assigned a bug from bugzilla to myself, and now I’m setting myself up with a bit of a unit-testing framework. We’ll see how it goes…

Calm Week

Nice week this week. I started out with an incredibly large and neat refactoring; it looked like it was gaining in size and complexity until a colleague reminded me to slow down, atomic commits and assign to each commit a specific purpose. It meant I stopped, took a few minutes out and worked out what the order and purpose of each commit was.

When I did that, it became incredibly clear what my order of operations should be, and it also became clear just how much extra value small commits have. I was committing bug fixes that were immediately available, instead of making coworkers wait for a code dump. It’s always good to be reminded of self-discipline.

I spent a bunch of night time working through the const keyword and its relationship to pointers. Here were the scenarios I wanted to understand:

const foo* bar = bam;
foo* const bar = bam;
const foo* const bar = bam;

Once I could conceptualise the idea that sometimes you want to track a constant address and sometimes you want to track constant data, and this is separate from using a variable to track an address and data because a variable actually encapsulates the memory footprint of the object as a whole, it all fell into place.

Beyond that, then, I watched a lot of Avatar this week. My girlfriend and I have really been into it; it’s such a cool little show. I’m really impressed by how consistent the writers have managed to keep it; it tracks its continuity really well, and is very consistent in how it portrays the power levels of the characters. Last night, we saw an episode from season 2 in which short stories are told about each character, and one of them has a story about how he’s sad that it’s X years to the day since his son died. It was pretty heart wrenching; I think both of us had tears pouring down our cheeks afterwards.

It’s weird how I cry far more easily the older I get. I’ve talked to a few friends about it, and they seem to be undergoing the same thing. I wonder what the deal is with that.

Yesterday, I had the task of wiping out a date stamp from a binary file format. I used a hex diffing tool to compare two versions of the same file to see what the offset was for the date, and then slowly nibbled away at an in-place edit using Perl. Normally, I use this as a template for my Perl in-place edits:


do
{
local $^I = '.bak'; //extension for an automagic backup file
local @ARGV = "somefile.txt";

while()
{
s/YEAR/$year/;
print;
}
};

However, yesterday this wasn’t adequate because I lacked knowledge of what byte patterns to throw in a regex. The more I thought about it, the more I was edging towards using read to slurp in the first X bytes, then spew them out into a temp file, spew out 16 bytes, then read from X+16 until EOF and spew that out afterwards.

At that point, it was clear that I should be doing an in-place edit still, but I didn’t understand my little template code correctly. So I sat down and wrote a few different example programs, working out the file handle relationships for in place editing. Eventually, it left me with something like:


open my $FILEHANDLE, "+< ${file}";
seek($FILEHANDLE, $offset, 0);
print $FILEHANDLE "0000000000000000";
close($FILEHANDLE);

And I felt like I’d achieved zen in filehandles.

Ellen Allien — Sehnsucht

Such a brilliant song.

The world’s moving by slowly, quietly. I’ve been spending my spare time mostly reading:

introducing html5, part of a series which, the publisher assures, is written by “voices that matter”. Quite what that means, I don’t know, but it’s a surprisingly fun book to wander through.
Beginning Visual C++ 2010. Visual Studio is a big mammoth of a tool, C++ is a big mammoth of a language. Together at last, I guess: seems like every page has a dozhundred things to remember, and I’m not even out of the chapters that are mostly concerned with the grammar and structures of C yet. Bloody ‘ell.
Javascript and Ajax, a part of the Visual Quickstart series of books. Surprisingly accessible, even downright funny at times. What’s with teh current trend of writing programming books that tickle you pink?

Still, my hope is that one day I’ll be some kind of lean, mean fighting machine on the web and desktop. Just give me ten years, I’ll get there. In the meantime: longing.

release cycles

I spent a lot of time yesterday thinking about the release model of “one major release, one minor release a month”, and about how websites have traditionally been on a “release ten times a day, who cares?” schedule. I was wondering if there was any proof one was bettar than the other.

And it crossed my mind that Google, traditionally a web comapny, stepped into the “we release binaries” market a long time ago, but with Chrome they stepped up their game bigtime: Chrome seems to release new versions so quickly I’ve never been able to keep track of the version numbers. Indeedle, the version numbers in Chrome don’t really mean much at all. Firefox is now on the same kind of release model.

I’m wondering if this is like distributed source control; we’ve just seen the first couple of big products to adopt a completely different way of viewing a traditional process, but it’ll take the rest of the world a few years to notice that it’s more than a flash in the pan.