On Empathy & Pull Requests

I’ve trained more people on the subject of pull requests than I care to remember.  But I’ve never came close to explaining the best practices as well as this Slack Engineering blog post does:

Basically, your reviewer is totally missing context, and it is your pull request’s job to give them that context. You have a few options:

  • Give it a good title, so people know what they’re getting it into before they start.
  • Use the description to tell your reviewer how you ended up with this solution. What did you try that didn’t work? Why is this the right solution?
  • Be sure to link to any secondary material that can add more context — a link to the bug tracker or a Slack archive link can really help when describing the issue.
  • Ask for specific feedback — if you are worried that the call to the `fooBarFrobber` could be avoided, let them know that so they can focus their effort.
  • Finally, you should explain what’s going on for your reviewer. What did you fix? Did you have any trouble fixing the bug? What are some other ways you could’ve fixed this, and why did you decide to fix it this way?

Not every pull request needs every single one of those things, but the more information you give your reviewer, the better they will be able to review your code for you. Plus, if someone ever finds a problem in the future and tracks it down to this pull request, they might understand what you were trying to do when they make a follow-up fix.

Give your reviewer all the context they need to get up to speed with your bug so they can be an informed, useful code reviewer. It’s all about getting your reviewer onto the same page as yourself.

How long is a ‘super quick’ meeting?

I’m still surprised by the number of people who don’t get this … Meetings are important and sometimes people have to be interrupted.  But just keep in mind that the 5 minute chat will probably throw off people for an hour.

Source: CommitStrip.

Multiple Perspectives On Technical Problems and Solutions

Multiple Perspectives On Technical Problems and Solutions” is an interesting take on engineering in general and software architecture in particular.  It starts off with:

Fundamental: engineering decision-making is a socially constructed activity

[…]

In other words, engineering (as an activity) does not have “correct” solutions to problems. As an aside, if you’re looking for correct solutions to problems, I’d suggest that you go work in a different field (like mathematics); engineering will likely frustrate you.

It then goes into dialogues and discussions, architecture review meetings, and provides a few pointers on how to get the best of those.

Atlassian Stride

Stride is a new product from Atlassian.  It is a re-branded and, hopefully, improved HipChat.  I haven’t tried it yet, but our team account will be upgraded soon enough.

To be honest, I’m not that excited about this move, but I’ll give it a benefit of a doubt.  I know there was a lot of hype about Slack recently, but I was really happy with HipChat.   I tried Slack for three days, and ran away.  But HipChat I can’t leave without.  It’s a much simpler and cleaner user interface, and it just works – completely out of your way.

Judging by the screenshots, Stride is a user interface upgrade to HipChat.  Atlassian has been moving to the new design recently with BitBucket and possibly other tools, so this part makes sense from at least their perspective.  Stride also brings free video calls, voice calls, and screen sharing.  HipChat had this option for the premium accounts (2$/month/user).  We tried it for a month and reverted, as the quality of calls and video was horrible.  And there were constant crashes and disconnections. Hopefully, Atlassian has put some work into these issues for the Stride release.

The most annoying thing about the upgrade from HipChat to Stride will be all the integrations.  Atlassian is promising to migrate all the data – history, files, custom smileys, etc.  But the best part about HipChat are the integrations.  We have a whole lot of them – GitHub, BitBucket, TravisCI, Twitter, WordPress,  Zabbix, and even our own custom ones, that we use for project deployments.  All these will have to be reconfigured and setup for Stride separately.  That’ll take a few hours here and there to get things back to where they were.

As far as the new features go, I don’t see too much yet.  Apart from the already mentioned voice calls, video calls, and screen sharing, there are just a couple.  Focus Mode is not really a big feature.  HipChat, much like any other messaging application, already had the status (Online, Away, Do Not Disturb, etc).  So Focus Mode is pretty much the same thing, with an extra time setting, so that you don’t forget to change you status back after a couple of hours.

Actions and Decisions is a nice addition.  You’ll be able to mark any message as an action or decision so that its easier to find and follow up on later.  But for us that’s not going to do much as we are already using Redmine for the project management.  Actions go into Redmine as tickets, and can later be referenced in commit messages, linked to each other, etc.  Having actions in Stride will probably work for very small teams with very few projects.  For us, we have a separate room for every project, every team, every office, and then some.  So searching for actions in a hundred-something rooms is far from perfect.  But maybe Stride’s search will be more powerful than that one of HipChat.  We’ll see.

Oh, and I’m guessing all the users will have to downloading and install new apps – for mobile, desktop, etc.  That’s yet another thing to do.

As I said, I haven’t tried Stride yet, and I hope it’ll be a huge improvement over HipChat, even though I HipChat worked great for me.  As I see it now, I think re-branding and the new design could have happened on the HipChat infrastructure.  Moving people to the new application altogether has to be justified by some major improvements.  And I’m not seeing anything major just yet.

The Minimally-nice Open Source Software Maintainer

Brian Anderson shares a few thoughts on how to appear as a minimally-nice Open Source Software maintainer.  Maintaining Open Source Software projects is a demanding job.  And the more popular the project is, the more demanding it is.  Brian shares the following practices that minimize the effort while you still maintaining a positive atmosphere for the project’s contributors:

In summary, do these things if you want to appear to be nice, and also if you want to actually be an effective open source software maintainer:

By consistently exhibiting a few simple behaviors, one can at least look like a kind and decent person. Maybe someday we all actually will be.