Separate, Communicate, Integrate
Posted on Fri 20 January 2017 in communication
Recently, I made a few changes to some tools that are in use by nearly all of the development teams with which I work.
Having been in this situation before, I had previously just pushed out the changes, fully confident that we would be able to deal with the sparse fallout from doing so, knowing that the solution would be a simple tool upgrade.
And truth be told, most stakeholders didn't even mind when that happened.
But the ones who did mind, despite a quick resolution, got awfully tired of having to contact us. Plus, they tended to be higher up in the org chart than us. Double oops.
Doing this was bad for many reasons, including:
- Stakeholders are powerless to modify scripts/processes to compensate for breaking changes.
- Over time, the team builds a bad reputation of having unstable tools.
- Incurs avoidable devotion of time for both the stakeholders and us to resolve.
- Embodies nearly all worst practices that Release Engineering stands for.
But, we have been successfully following a new, common-sense mindset that can be summed up in 3 words (that all rhyme to make them easier to remember):
Separate, Communicate, Integrate
Step 1: Separate
Ever hear of a "sandbox?" Its meaning differs with each organization, however it's a term generally used to describe the isolation of a particular process, file, codebase, or system from other systems. Setting up a separation for your changes allows for free experimentation, plus it provides insurance against accidentally breaking anything.
In Git, this can be a simple fork of an upstream codebase. In Docker, this could be a different tag on an existing image. In Salt, a different hierarchy within a pillar file.
Whatever changes you make, ensure that you first have some separation between what is currently being used in production from what you have modified.
Step 2: Communicate
Once your changes are complete and are ready for general consumption, first draft an email, write a wiki page, or otherwise document your changes (no, only comments in the code don't count) via whatever documentation media your org uses.
What works for us is six-fold:
- Comments in the code
- A maintained man page
- A maintained in-repo README.rst file
- Email to the wider engineering org about the changes
- A broadcast chat room message in our team room
- Monthly team newsletter about changes we've made
Yes, that is a lot. But even so, we still get stakeholders asking questions about changes that have been documented and accessible through all the usual methods and channels. This is likely why advertisers often talk about the importance and efficacy of repetition.
Pro tip: get some kind of acknowledgment from your stakeholders that your message has been received. Remember, this is communication, not dictation, which means it's a two-way street. Heck, even TCP/IP uses a 3-way handshake!
Step 3: Integrate
Once you have communicated through a reasonable number of channels and you've ACK'd your stakeholders' SYN-ACK (read this if you don't understand that reference), now it's time to roll out your changes, whether it's a merge into a codebase, kicking off a pipeline, uploading to a filer, or all of the above.
There could be a "Step 4: Communicate again" here, however, remembering the Golden Rule should be enough to help guide you in your next steps at this point. Plus, 'Communicate Again' doesn't rhyme with the other three.
Conclusion
The next time you're excited to enrich the world with your new changes ASAP, take a sec and remember "Separate, Communicate, Integrate." It'll save you, your team, and everyone else involved time and brainpower.