Wednesday, October 31, 2012

How I Do Pull Requests

I've been working with a couple new developers lately and we've been talking about how we actually write, review and check in code. Early on, we all agreed that we would use a shared repository and pull requests. That way we get good peer code reviews, and we can look at each other's work in progress code.


One of the developers approached me after that conversation and said, "umm, so how exactly do I do pull requests?" On Github, here's how I do it:

# CD into the project
$ cd Documents/project/project_repo/

# Check what branch I'm on (almost always should be master when I'm starting a new feature)
$ git branch
* master

# Pull to make sure I have the latest
$ git pull
Already up-to-date.

# Make a new branch off master. This will be my feature branch and can be named whatever I want. I prefix all my feature branches with cmp_ so people know who did most of the coding on it.
$ git branch cmp_NEWFEATURE

# Switch to my new branch
$ git checkout cmp_NEWFEATURE
Switched to branch 'cmp_NEWFEATURE'

# Commit my changes because they're awesome
# Develop more stuff. Make changes, etc.
# Commit my changes, because they're awesome.
# Pull from master and merge to make sure my stuff still works.
# NOW I'm ready to make a pull request.

# push my branch to origin
$ git push origin cmp_NEWFEATURE

# Create the pull request
# I do this on github. See
# Set the base branch to master and the head branch to cmp_NEWFEATURE

# Twiddle my thumbs waiting for the pull request to be approved.
# When it's approved, huzzah!

# If the reviewer said, "go ahead and merge", then the merge is on me to do.

# Check out the master branch. This is what I'll be merging into
$ git checkout master

# Merge from my pull request branch into master. I use --squash so the whole merge is one commit, no matter how many commits it took on the branch to get there.
$ git merge --squash cmp_NEWFEATURE

# If the merge isn't clean, go ahead and fix and commit.

# Push my newly-merged master up to origin. The pull request is done!
$ git push

# Go into github and close the pull request. I do this in a browser.

# Delete the feature branch from origin. Tidiness is awesome.
$ git push origin :

# Delete my local copy of the feature branch.
$ git branch -D

More information can be found here:

Happy pulling!

Friday, October 26, 2012

Use Your Own API

One of the early milestones for an engineering team is the development of the first API. Someone wants to use our stuff! Maybe it's another team in the company, or another company altogether. Either way, someone will be consuming your API.

That's truly awesome news. It's always fun to see the great things teams can accomplish with your work.

So how do we create an API? Most of this is fairly straightforward:

  • Figure out what people want to do
  • Create an appropriate security model
  • Settle on an API model (RESTful JSON API? XML-RPC? Choose your technologies.)
  • Define the granularity and the API itself.
  • Document it: training materials, PyDoc/rdoc/javadoc, implementation guide, etc.
The trouble is that most people stop there. There's actually one more step to building a good API:

Use your own API.

All the theory in the world doesn't replace building an application with an API. Things that seem like great ideas on paper turn out to be very painful in the real world - like a too-granular API resulting in hundreds of calls, or hidden workflows enforced by convention only. Things that seemed like they were going to be hard are easy. Data elements show up in unexpected places. This is all stuff you figure out not through examination, but through trying it.

So try it. Create an API, then create a simple app that uses your API. It's amazing what you'll learn.

Friday, October 19, 2012

Mind Your Words

When you're surrounded by other engineers all day, it's easy to forget that some words have other meanings. Take "CRUD", for example. In engineering, that's shorthand for Create Retrieve Update Delete - your standard data operations. In real life, it's a derogatory term.

At several of my client sites, we use CRUD as engineers do. "Yeah, I've just implemented the CRUD operations; it's not pretty yet." "That's just a CRUD workflow? Yup!" "CRUD looks good."

When you get in front of non-technical folks, though, that exact conversation takes on a whole new tone. All of a sudden, you're a coarse, derogatory engineer. Oops!

Long story short, mind your words. Context changes meaning!

Tuesday, October 16, 2012

Management by Monopoly Money

I work with a lot of different teams, and almost all of them have some concept of a backlog. Basically, it's a list in some approximation of priority that the team works from. How they pull off the backlog and how stuff moves around the backlog varies a bit, but that's the basic idea.

One of the frustrations with this kind of backlog management is that certain things get short shrift. The person who owns the backlog has - through no fault of their own - certain biases. Often, it's whoever shouts loudest or most recently, or things that relate to that person's background get priority (e.g., an ex-IT guy will prioritize technical debt and deployment/monitoring items, while an ex-sales person will prioritize customer and sales requests). This leads to fun conversations and ideas like, "well, 10% of our stories should be paying down technical debt," or "every fifth story should be a customer request." In theory this works well. In practice, things aren't nearly that smooth.  In practice, sometimes things come up and we skip our customer story in favor of a strategic priority, or we don't hit our technical debt goal.

There's another way.

Yup, Monopoly money!

It sounds silly, but bear with me. When we make statements like, "10% of our time should be on technical debt", we're talking about a budget. So let's use budgeting tools - money.

Here's how it works:

  1. The product owner and management work to set a budget. It usually is as simple as agreeing that sales gets 25%, product management gets 50%, engineering gets 25%.
  2. Set a total budget amount that reflects the total amount of work you expect the team to accomplish.
  3. The representative from each group gets monopoly money according to their proportion of the budget. Usually it's a dollar a point (or $10 a point, if you're feeling rich).
  4. As you create the backlog, each group spends their money. When they're out, they're out.
Try to keep your budget over a fairly short period of time - a few sprints, or no more than a quarter. That way there's a reset opportunity before anything gets too skewed.

This turns fun very quickly. By providing money, you're creating an economy. The IT guy will trade away some of his money in exchange for getting it back from marketing next quarter, for example. Or two groups will band together to outspend everyone and push a feature they don't want onto the backlog. It also makes the process very concrete. There's no stretching or remembering. There's just how much money each group has left.

Making abstract work concrete and sticking to a budget.... now that's worth a shot. Give it a try.

Thursday, October 11, 2012

Installing Umbraco Packages

Just a quick tech note today, for anyone using Umbraco.

I was attempting to install a package from the Umbraco package repository and kept getting an error: ERR_NAME_NOT_RESOLVED. It looked like a DNS error, but I couldn't find any DNS problems!

I finally found the right answer: it's the world's most poorly formed permissions problem. Give your IIS user read, write and execute permissions on c:\Windows\Temp, and the problem will go away.

Tuesday, October 9, 2012

The Overloaded Tester

As most of you know, I came up through software testing, before branching out into development and management. I still like to keep in touch with my roots, and spend a lot of time working with my clients on the test function in software.

I've noticed a trend recently toward overloading the tester. It's no longer fashionable to simply have testers. That's "old school" "retro" thinking that produces script monkeys and poor manual testers. The bright shiny way now is to have test automation gurus - basically developers who specialize in developing tests and test frameworks - and a customer or customer proxy who helps define what to test.

All in all, I don't have a problem with the thinking behind the trend. Yes, script monkeys give testing a bad name. Yes, test automation can be a hugely valuable tool. Yes, listening to the customer is great. Like many trends, it went too far, but it's starting to swing back. And that's where things are getting interesting.

You see, we have all these manual testers, and some of them are very good. Some of them know the business and the uses like the backs of their hands, and we're starting to recognize how valuable that knowledge is. Others know the attributes of testable, maintainable, scalable software and can be great testing in the code review or architecture era. What we used to call a manual tester can now be a great future proofer.

We're really starting to overload the tester. Now instead of hiring a senior manual tester, we see job reqs for a senior tester that include phrases like:

  • "owns the quality process"
  • "evangelist for good software development and delivery practices"
  • "works across the organization to instill a culture of quality"
Your most senior testers are becoming - at least in some places - process gurus and influencers more than testers. They may never actually test a piece of software.

This actually isn't inherently a good or a bad thing. Some companies have experimented with similar ideas on the development side for years, often under the title "Office of the CTO". It's a kind of roving expert consultant who works exclusively within one company but works across the organization. Seeing this start to come up in testing.... well, it's a career path for testers who don't want to get into managing people.

I think overall I'm for this trend of testers taking on a broader role in the organization. Just be careful you know what you're getting into!

Wednesday, October 3, 2012

Team Neutral

I have a client who has outgrown their scrum team. Daily standups are taking longer and longer, and the team doesn't really fit into their room very well at all. Sprint planning is getting more and more... fun, too. And by fun I mean long.

So we're splitting the teams. Going forward, we will have two functionally equivalent teams. First order of business: a team name!

Sounds simple, right? Nope, not so much. Let's back up for a second.

This isn't the first client I've had who's split teams. The last client that split wound up with three teams needing names. And then the fun started. One team suggested greek alphabet as a theme. They would, of course, be Team Alpha. The second team would be Team Beta. The third team would be Team Omega. Team Beta was particularly unamused. Another team suggested a theme of 80's TV shows. They would be Miami Vice (cool cars!). The second team would be Growing Pains. The third team would be the Golden Girls (this team, incidentally had no women). Neither team was amused. The third team suggested a simple numbering system. They would be team 1. Someone else would be team 2. And the last team would be team 3. The squabbling continued.

It took about three weeks to land on colors as a relatively neutral theme. Granted, this was an extreme example of a group that collectively contained some pretty fragile egos and a highly developed sense of hierarchy.

The underlying point is interesting, though. It's useful to give teams names. After all, we have to refer to them somehow. It's also fun to let teams pick their own names.


Make sure those names are neutral and don't imply positioning or relative importance in any way. Neutral things like colors, places, video games, and others are a good idea. And make sure every team gets to pick their own name.

One day, I'll get to be on Team Neutral. Until then, you can find me on Team has-a-neutral-name.