Originally posted on our Medium blog.

Today I had a fun bug; all our release commentary disappeared off the face of the world. You see, I’m a lazy developer (‘like all good developers,’ I tell myself); I attempt to do the minimum amount of work to achieve my goal, I don’t repeat myself, or my data. And that’s what came back to bite me.

When I implemented our Release Commentary system I though ‘oh, JIRA has our release comments, I’ll just go fetch them from there’. Good idea, no? It means that we have a single source of truth for our issues, their resolutions and their effects. It even means that publishing a release comment (where required) is baked into the workflow.

All in all I was pretty proud of my solution. So why did it break?

Well, we’ve been reviewing our workflow recently and updating it with all the learnings we’ve acquired over the last few months. And that meant making a few changes in JIRA. A side effect of which: the query to build the release commentary had changed.

Now, look - I’m a responsible dev. I leave a wake of tests behind me; beautiful behaviour driven essays that would make Kent Beck cry (prove me wrong :P). Of course, none of them detected that the release commentary had disappeared. Why? Because my tests don’t run against JIRA’s actual API, they run against a mock.

This mistake is 100% on me - I administer JIRA, I wrote the integration and I made the change that broke it. I can’t even hide behind the ‘knowledge management/sharing is hard’ excuse, because I was the only one in this loop. Yes, better integration tests would have picked up the issue, although they’d probably have been a bit elaborate for the actual hazard involved (I mean, it’s a change log we’re talking about here, not a nuclear missile.)

So, what have I learnt?

Interdependencies are hard. You can never assume that only one side of the interface will change- and so both sides must be protected accordingly.
Lesson learnt.

But how do I affect it? Well, in my case I had the tests on one side to protect me. JIRA, of course, doesn’t have a “Remember that thing you did a few months ago? It’ll break if you change this” dialog option, alas. So, instead, I have put a reminder of the connection as prominently as I can (our workflow is now called ‘Version 3.0: Warning, linked to api-release-comments’).

Here’s hoping I don’t break it all next time.