MettaProgramming

Here at CHOAM, we love to live at the junction of creating and learning. In fact, it’s one of the primary reasons I became a programmer. As a little kid with my TI 99/4A I could create software I never dreamed possible. Sitting down with my BASIC compiler, I could type a few lines of code and suddenly do something that I could never do before. I’ve been creating ever since, the ability to create was too addictive to let go.

Software is a world where you need to improve your skills everyday.¹ That’s a heavy toll, but a wonderful one, because you’re always just about underwater, you’re always challenged. But, and this is the wonderful part, you’re always discovering. Every day as a developer is a day that I am doing something that I haven’t done before. Whether it’s creating a new architecture, or just improving a workflow. Everyday is about improvement.

Problems with The Ever-Deployable Git Workflow

I’ve been using my Ever-Deployable Git Workflow for a few months now with much success. It’s been a great way to keep a project up to speed with multiple people working on multiple issues with barely any conflict. Still, nothing is perfect.

One thing I’ve found is that naming branches is problematic. Few people want to type “git checkout -b make-javascript-popups-easier-to-maintain,” it’s just too long. Also, searching through a long list of issues with names like that just gets troublesome. What is John working on? Oh, something about making Javascript popups better. Well, is that Issue #216? The one about JS file location? Or is it Issue #384?

This brings up two ways that we can make the Ever-Deployable Github workflow better. First, unify with the issue tracker, and second, make better branch names.

The Github Issue Tracker

Github’s issue tracker is probably one of the least functional issue trackers I’ve ever used. It basically has nothing you’d expect or want. It’s little more than a title, some text, and maybe a label.

For that reason, it’s the best issue tracker I’ve ever used.

How many of us get sucked into the feature set of a piece of software and end up spending all of our time maintaining the software. Github’s issue tracker forces us to avoid that tendency by not giving us that feature set. It’s brilliant. All I can do is write a title, write a description, and then get back to work. It makes logging issues super fast. So recently, I’ve started to take advantage of that. I log issues for nearly every small, atomic change I want to make.

Furthermore, you can close issues with commit messages like “Fixes #216 by shuffling the JS files as if they were a deck of cards,” and the commit then gets linked to the closed issue automagically. It’s really a great system.

10 Steps to a Better Workflow

So, we have a way that we can quickly make issues to log things we want to change. And we want to get rid of insanely long branch names. Why don’t we branch the issue? This means our branch name is minimally descriptive, but there is as much description as we want in the actual issue. Using this methodology, our new Github Workflow is this:

1. Only work on documented issues. The idea here is that no one is ever just blindly mucking about in the code without a documented reason²
2. Look to see if anyone else is working on the issue you are going to start.
3. Create an issue describing work to be done, or use an existing issue
4. Create a branch using that issue number. We use “issueNUM” as the branch name, so something like “git checkout -b issue516″
5. Immediately, before doing any work, push that branch back to master: “git push origin issue516.” This tells everyone that someone is actively working on this issue. This is why you don’t work on undocumented issues. It’s very easy to know what the entire team is working on.
6. Work on your code following The Ever-Deployable Github Workflow. Making commits fairly atomically, or as atomically as your team decides.³
7. Rebase to master
8. Commit the branch with a final message like “Fixes #517 by doing lots of stuff.”
9. Push to remote, submit your pull request, and “git checkout -b <nextIssueNumber>”
10. Lather, rinse, and repeat

Fixing other things along the way

This workflow has done a few things for us. One, it encourages atomic work on the code. By that, I mean it encourages us to stay away from commits that change “a little of this, little of that.” We are working on a single issue, and our branch is named with that issue. So we focus on that issue.

If we want to fix other, most often very small, issues during the work, we fix them in a single commit, and log that in the commit message “Fixes #214 by changing something, since I’m here already.” If we want to fix bigger issues, we do it a bit differently.

For instance, say we are working on our issue #516, and during that, we come up with a decent way to correct another issue, say issue #212, that comes up because of our work on this one, but which we don’t want to dump right into production- maybe we have to test it more:

git checkout -b issue516
git push origin issue516
… do some work and decide to fix issue 212, but not to push it to production without first finishing 516
git checkout -b issue212
git push origin issue212
… fix 212 and commit
git commit -am "Fixes #212 by mucking about in the code"
git push origin issue212
git checkout issue516
… continue working on issue 516
git commit -am "Fixes #516"
… then do the standard git rebase workflow:
git checkout master
git pull origin master
git checkout issue516
git rebase master
… Then submit your pull request for Issue 516. Now, it's a good time to push up 212
git checkout issue212
git rebase issue516
git push origin issue212

With this, issue212 is fixed on top of issue516 and is ready for either a pull request or more review and work. From a git log perspective, it appears that issue 516 was completed, and then issue 212 was completed. Nice and clean.

Coda

I’ve been using this workflow on various teams for about 2 months now, and it’s working out extremely well. I’d be interested in what you think.

1. Admittedly, there are those who don’t. But I try to keep them far away from my projects. Nothing is more dangerous than a developer who is happy at being stale [↩]
2. or at least without creating an issue like “Issue #516: Blindly mucking about in the code” [↩]
3. I like smaller commits, since they are easier to review and revert [↩]

I’ve been working full-time as a contract programmer for a few years now, and have recently begun to realize something very disheartening:

My clients get a lot of shit for free.

Now, that’s not disheartening in a “they get stuff I don’t get” sort of way. I mean, good for them. I’m a happy person who likes spreading happiness, so I’m not against them getting shit for free on principle. The problem here is that my clients get a lot of shit for free that I do– and thus, it means that I’m doing a lot of work for free.

Today is a perfect example of this. Today I did some quick work for a client that submitted a request using my ticketing system. Since I wasn’t actually working for someone else at the time, I went ahead and tackled it. The time I spent on that, from initially seeing the email to completing it barely scraped 20 minutes. I loosely round to 15 minute increments, and generally don’t charge for a quick 5-15 minute bit of work. Thus, I did that for free.

Then, since I was already outside of a context, I checked my email, and there was another request. Similar thing, similar outcome. A wee bit of unbilled work.

Then, there was another request from another client. This one took about 45 minutes. So, I went into FreshBooks and went to bill them, only to realize that it was the first time I was billing them this month. I’ve worked for that client almost 4 times already this month, and this is the first time I’ve billed them.

I am extremely hesitant at this point to back calculate just how many of these little things I do without billing.

Metric billing

When I was working in environmental consulting¹, I had this ridiculous billing sheet that I had to keep. It was 10ths of an hour, which makes sense from a percentage perspective– easy calculations– but becomes mind-numblingly frustrating when you have to actually write down the fact that you used two billing increments because it took you 10 minutes to go to the bathroom!

I mean, think about that: 10ths of an hour: 6 minute increments. Imagine tracking what you do by looking at every 6 minutes! “No, I don’t have time to glance at your stupid Star Wars link, that’s like 2 whole minutes!!”

I thought I would go crazy at that job. And yet, oddly, lately I’ve become to realize that it makes an insane sort of sense. My base rate is $85/hr, which means that one of those billing increments is effectively $8.50, which means that my “barely scraping 20 minute” task that I did for my client was worth $25.50.

Again, I am extremely hesitant at this point to back calculate just how many of these little things I do without billing.

Small clients, hourly work, and the fallacy of ‘free’

And so we have a problem. I basically refuse to bill more harshly– admittedly out of my own laziness– but continue to have lots of small contracts which, by their very nature, necessitate harsh billing. It makes my relationship with my clients more lopsided, which doesn’t stay positive. I’m starting to realize that this is far from a “good deal” for my clients. In fact, it’s a pretty bad thing.

Think about it. I do work for my clients for free, and I do this free work all the time, right? That’s great because my clients are getting stuff and not paying for it, right? Wrong. The more I do work for free, the more working for this client becomes a burden, either real or perceived, and the worse my work gets. I get less engaged, and more frustrated, with every task.

That’s not good for either of us. Good business isn’t about getting shit freely. That’s a fallacy. Good business is about getting shit fairly.

I understand the lawyers

Lawyers. Those bastards.They do this thing which I always thought was really shitty and unfair. They charge you for work they don’t do. It’s this scam they have called “being on retainer.”² They charge you this monthly amount for work they “might” do. If you call them, you pay. And if you don’t call them, you pay. Then, if you want them to do a lot of work, you pay more!

I understand this now.

Lawyers aren’t bastards at all, and they are not scamming at all. It may not be perfect, but what they are doing is trying to get as close as possible to “fair.”

This is why my lawyer doesn’t charge me when I call to ask a simple question, yes. But more importantly, this is why my lawyer is actually engaged when I call to ask that simple question. I now realize why the lawyers do what they do, and I have to say that it’s a seriously good idea.

I’ve got a couple clients that I don’t hear from for months, who will then call with work for me to do. This is a bad situation. Since I’m not getting paid unless they call me, I have to take on other work, so I fill my schedule, book myself up, then get this call from someone asking me to do work, and I can’t.

At that point, I have no time for work. It’s not like I set aside time just in case they called me. I can’t do that and survive. So we’re screwed. There’s no good solution, and anything we come up with is the least crappy choice of either “fitting it in” or doing a less than perfect job just to “get it out of the way” or even saying “sorry, you’re out of luck.”

From now on, I’m on retainer

Here’s the thing: I want clients who value their own work, who take their own work seriously– seriously enough that they demand that I take it seriously. Because I take my own work seriously. I spend enormous amounts of time working to improve myself, to work better. I value my work, and I want clients who value me.

I’m no longer working hourly for any contract that is not a significant portion of my time. My plan is to set a “retainer rate” at some fraction of my base rate, which my client will pay monthly in exchange for me guaranteeing that they have a certain amount of hours. Those are hours that I don’t have to fill with other work. Those are hours I can set aside for my client, and if I don’t use them for my client, then great, I use them to work anyway, learning another framework, or another language, or just playing with a design pattern, or refactoring something in their code. All of which makes me better, and more valuable to my clients.

It’s all about value.

Retainer doesn’t mean “I’m charging you for work I might not do.” Not at all. I see that now. Retainer means “I have to find work, and you’re going to get shoved aside and treated like shit, unless I don’t have to find work.” Retainer means “You value your business enough that you don’t want stuff to ‘maybe get fit in.’” Retainer guarantees access, but more than that, it guarantees fairness.³ It says “I care about my product, and I care about it enough that when I want you to work, I don’t want to wonder whether you can.”

It shows that the client values their product, it certainly shows that the client values me, but most of all it shows that I’d damn-well better value this client.

That, my friend, is good business.

1. during my short, foolish attempt to convince myself that I’m not a developer in my heart [↩]
2. Yes, I realize they are not the only ones who use the retainer, but they are my foil for this article, so shut up. [↩]
3. or, at least, comes as close as we can get easily in our system. [↩]

You know the old saying, a derivative of: “Test are like flossing, we all know we should write them, but no-one does.” That’s an old saying because, while it was true 10-20 years ago, it’s not so true now. For the most part, the modern development world is a beautifully tested one. These days, nearly everyone flosses.

Still, there are always improvements. Sure, we test, but maybe we don’t really test the web interactions, or test the controllers as well as we should, or whatever. We’re flossing, but we’re not really flossing as well as we could be. We’re missing some teeth.

Today, I got a toothache.

Mock your services

My company, Hydrasi, has what is a fairly common architecture these days. We have a front-end website (in Rails) that sessions users and does various pretty things, and we have various back-end servers (our main is in Scala) that do things like manage data, send messages, etc. Everything connects to everything else via messaging and API calls. This is basic “concern separated” design. The Rails site shouldn’t care what the hell happens in the Scala server, it should just care that when it says “give me a monkey,” it get’s a monkey. It’s a nice separation because I “own” the front end, and my partner “owns” the back end.

And yet, with all of this architectural decision making and best practices, today I’m at a work-stoppage point because my front-end tests are failing. Why? Because I’m an idiot and built them all while I had a back-end server that was functional. Today, that service is *not* functional, and my partner is out, probably doing what he should be doing on a Saturday– having fun.

Yes, I feel really stupid. I spent an hour trying to hack around and get the back-end services running so I could work.

Yes, I already feel stupid, and yes, it’s obvious that I haven’t really been flossing.

So now, instead of working on what I thought I was going to work on, I’m heading over to grab the FakeWeb gem so that next time I work, it won’t matter whether any other servers are running.

(in a month, I’ll write a post about how I forgot to write integration tests

This is the last in my posts about why I left Facebook.

No, really, I promise!

Like many things I write, they’ve come off a bit as “explanation” and/or “justification,” but– also like many things I write– they were meant more as “exploration.” They are a personal exploration, through writing, of my own decisions and motivations. That is what writing is to me. That ability to use it as a forum, not with others, but with myself. It’s as much an internal dialog as an external representation. It is more-so that, actually.

And that’s the point of this post.

Longform writing

I’m going to be honest with myself and not describe the way I like to write as “essay.” It often doesn’t have the deep research and editing that such writing would require. Still, it is longform writing. It’s not sound bites, it’s analysis. It allows me– forces me, really– to dive deeply into myself to ascertain my own thoughts and motivations. Whether I’m writing about myself, or about someone else, or about some arbitrary situation removed from me completely. Writing is analysis.

Facebook is not writing as analysis. Facebook is a focus on the soundbite. Facebook is a headline. Headlines are catchy. They are short and pithy. Headlines grab people’s attention, and Facebook is really good at that. But that was the limit. Longform writing is the actual story, and I truly believe in “story.”

Longform writing is what I want to do, but Facebook writing is what I did.

Strangely, I would find that I was spending almost as much time internally preparing a Facebook post as I would spend preparing a longform blog post such as this. And no, that’s not to say that I spend only a few minutes preparing a blog post. What that means is that a stupid Facebook post would take, quite literally, days to prepare.

Just think for a moment about how incredibly fucking stupid that is.

I mean, seriously, did you read the previous posts where I describe how I don’t take Facebook seriously? Good. So I’m not the other one who realizes that I’m completely full of shit. I take it too fucking seriously!

A day to swim, a week to post about it

Think about this small post:

The Hood River pool, where you learn that no matter how out of shape you thought you were, you’re more out of shape than that.

Which took me almost a week to write. Yes, you read that correctly, almost a week.

I’ve written before about trying to learn how to swim with the masters swimmers. It’s difficult, but it’s also amazing who’s there. There are 60+ year old women who, despite my best efforts at focusing on what I’m doing, I can’t help but notice are really in shape and… well… hot! There are people who are so in shape and so good in the water that it’s difficult to believe that I’ll ever be that good.

So, I’m there watching people who I can’t help but compare myself to– me, this former martial arts loving competitive cyclist who is now little more than an out-of-shape middle-aged oaf. I watch them while meanwhile I can barely make it back and forth across the pool once before I’m out of breath and dizzy enough to pass out.

And there’s this aspect of body preparedness, which I’ve never thought of, but which explains why I can get on a bicycle after two years of doing basically no riding, and still hold my own in the Tour de Hood. It’s the reason I keep thinking of myself as “fairly fit” despite all the evidence to the contrary. It’s not that I’m “fit.” It’s just that my body, after an entire lifetime of doing this sport, is uniquely prepared to, well, do this sport.

But any other sport is up for grabs. I can ride 40 miles at the drop of a hat, but jogging around the block is deadly, and swimming kicks my ass.

That’s a sampling of the analysis I did before writing that Facebook post. It’s a sampling of what I wanted to write about. But, of course, on Facebook, you’re not going to write all of that. So, I took a couple days thinking about that, then a couple more deciding whether I was going to write about 60 year old women who look hot in bathing suits, and how I could do that in a way that was funny, but still appropriate and respectful to them, and then a while deciding whether I was going to mention body preparedness or just feeling out of shape, and a couple days to…

And what do I get out of that? One fucking sentence that doesn’t express any of that.

Don’t give up writing for writing

Here in Hood River, wind sports are big. The windsurfers and kiteboarders here have a saying: “Don’t give up wind for wind.” There’s a lot I learned from that saying.

Say you’re out on the river, and you have wind, and you’re windsurfing, but then you look way up the gorge and it looks windier. You might be tempted to go there, but you shouldn’t. You have wind here, and you don’t know that the wind is better up there. Furthermore, even if it is better up there, by the time you get off the water, break down, get there, rig up, and get back on the water, that wind could be gone. That wind could have left by that time– and the wind you had at the first place could have left too.

Don’t give up wind for wind.

I realized that what I was doing was just that. I was obsessing about posts. Do they capture everything I want them to capture, do they have enough comedy, do they poke at, or not poke at, family members who will be upset, or not upset, at being poked at. I’d spend a week thinking about how I was going to post a short two sentence statement on Facebook, and I found that I had no mental energy for actually writing the longform analysis that I wanted to do, so I didn’t do it. I was doing all the longform analysis for shortform writing.

I gave up writing for writing.

Archery and The Final Twist

But that’s not even the real, really real, reason I gave up Facebook.

I obsessed over Facebook posts. I would literally sit with someone in conversation and think about how I was going to relate that conversation– or maybe even think about how I was going to relate a completely different conversation on Facebook. At the pool, I thought just as much about how I was going to relate my experience at the pool on Facebook as I did about how I was actually experiencing the pool.

I had inklings of this for a while, but it hit home when I was practicing archery one day. Coming from a martial arts background, I have a consciousness of focus and presence. I use that in many things, of course, but I’m more conscious of them when I do martial arts-like things, of which archery is one. So one day, I’m out shooting, and I shoot a really beautiful quiver. I was calm, focused, present, and 5 of 8 arrows are all virtually dead center and spaced about the distance of two quarters. Beautiful.

Now, what I should have done, what I knew I wanted to do, was to ignore those arrows that I’ve already shot. They don’t exist. I needn’t think of the two arrows still in my quiver either, because they don’t exist. The only thing that exists is this arrow I have nocked and the target. There is nothing but this shot. Quiet, peace, breath, and this one shot are all that exist in the world. That is what I should have thought.

But what I did think is this: Wouldn’t it be awesome to post a picture of 8 perfectly shot arrows in the target! I’d love to post that on Facebook.

The next shot I fired was almost a foot off. The shot after that missed the target all together. My final shot even missed my backboard and hit my shed. I realized at that point that I hadn’t given up writing for writing. I’d given up the presence of my life for Facebook.

I unstrung my bow, collected my arrows, came inside, and deleted my account.

A Farewell To Facebook

Me leaving Facebook had nothing to do with the concept of friends, or with the concept of interaction. It had to do with the concept of presence. Specifically, with my inability to have that presence while I was focused on my obsessive, stupid desire to describe that presence to others.

Sure, I think about how I’m going to post something on my blog, but it’s different. I can’t explain how it’s different except to say that when I think about my blog, I don’t actually think about how will I say this on my blog, but rather I think how do I feel about this– and then I write about those feelings on my blog.

Maybe it’s because longform is the process of understanding of how I feel about something, and then the writing of those feelings. It’s focused on the feeling, the understanding. Shortform writing is, for me, often focused on just the writing.

I can’t explain it, really. But I know that when I was standing there with my bow in my hand, looking thirty feet beyond my target at a fletching sticking out of my shed, I wanted to cry. I wanted to cry not because I missed a good shot, or because I missed the opportunity to describe that good shot, but because I was thinking so much about Facebook that I missed the experience of living that shot.

And of so much other living.