Speakerline

Branch in Time, by Tekin Suleyman
#revisionhistory #storytelling #git

Abstract

In one timeline, a quick path to clarity. In the other, a long and painful journey trying to understand the obscure intent of a line of code. The only difference between the two realities? The revision history...

This is a story about writing maintainable software. But rather than the code itself, we’ll see how a well-crafted revision history is as important to maintainability as choosing the right abstraction. We'll explore the differences between a useful history and an unhelpful one. And you'll learn about the practices, tools and techniques that help make the difference.

The Pitch

We document what our code does in many ways: the abstractions we create; the well-named classes and methods we write; the tests we maintain. Perhaps even actual documentation! But if we want to know the why of our software, how it got to where it is today, the revision history should be the first place we look. Software is never "done". It evolves and shifts, often in unexpected ways, with many decisions, trade-offs and compromises made along the way. With the right care and attention, we can document our decisions to make them available to future developers long after we’ve made them. This becomes increasingly important as our applications grow and age, and as developers leave and join our teams. Unless we take the time to carefully curate our revision histories, these decisions, and the context in which they were made, will be lost forever and the job of future developers will be that much harder.

But until you've seen how useful a well-put-together revision history can be – or felt the pain of a bad one – there's every chance you won't have the motivation or appreciation to put one together in the first place.

You first need to understand how the tools can reveal it. This means going beyond git blame and learning how to wield git log, with its powerful but esoteric option flags, to pull out bespoke and targeted histories on the specific code you are trying to understand. Once you've seen the treasures you can unearth, and learnt the techniques to do so, you will be better equipped and motivated to shape your commits and write "good" commit messages; things that otherwise are easy to dismiss as pedantic fussiness.

This talk will take the audience on this journey in an accessible way, and leave them with the motivation and tools to start writing more maintainable software today.

Details

This talk falls into two parts. Part 1 is a story illustrating the difference between a well put-together revision history and a less than stellar one. In Part 2, I talk more generally on revision histories and software maintainability before sharing some practical tips that audience members can use to create better revision histories, and ultimately write more maintainable software.

The Story

The story is about Seema, a developer who is struggling to understand the intent of a surprising line of code. She uses various Git techniques to look back through the revision history and solve the mystery, but ultimately fails. We jump back in time to see how we got here, with Josie – the original developer – having a bad day and leaving a not particularly helpful history. Then we shift reality and go again, this time with Josie using various Git techniques to construction a more helpful history. Back in the future, Seema this time quickly gets to the answer she struggled to find in the other timeline. Think Sliding Doors, but with more Git!

The story is used as a fun and engaging way to illustrate two important aspects of the revision history: Firstly, that we can use specific Git techniques to search back through time and uncover the truth behind the code we see. Secondly, that this is only possible If we take care to shape our revision histories in the first place. It aims to show in a concrete way the impact the revision history can have on the maintainability of the software we write.

Some of the techniques and practices that are covered in this section include:

git blame as the simplest tool
moving onto git log -S (the pickaxe) to search back through the history and trace the evolution of a specific piece of code across multiple commits
Using git commit --amend to tweak an existing commit
Creating a "fixup" commit with git commit --fixup, and then "autosquashing" during a rebase
A demonstration of an interactive rebase where: several commits are merged to make a single atomic commit; another commit is edited to create two separate atomic commits; and some commits are reworded to give them more useful commit message
Using --force-with-lease to protect against overwriting somebody else work.

Part 2

In the second part of the talk I bring the message home, summarising the ideas that the story helped to illustrate (see the pitch below for a summary of the message). I then conclude with a series of simple, actionable tips and steps that a now-motivated developer can use to search through their histories, and improve the revision histories they leave behind.

Outline of the things I cover in the tips part:

Create the environment for writing good commit message (simple things like: configuring your editor and enabling verbose mode to create an environment that encourages and enables you to write better commit messages)
Capturing the why, not the what (A quick primer on writing useful commit message, including a couple of mind hacks to get you started)
Build your instincts; search your histories (ditching git blame and reaching for the pickaxe instead; gaining an appreciation for the sorts of commits/histories that work, and the sorts that don't)
Shaping your commits (strategies for shaping useful commits: from git add -p; to git rebase --interactive)
Treat your commits as mutable (getting used to reshaping your local history to maximise the history's usefulness)

Audience and Outcomes

My primary target audience is the developer who cares about the maintainability of the software they write, but perhaps hasn't yet seen or appreciated the impact the shape of the revision history can have. By the end of the talk I want to have convinced them of its importance, and also equipped them with simple practices and techniques for both creating better histories, and searching through the histories they work with. My talk will still be interesting for those that already have these skills, and includes a specific message for them on the best way to help others improve. I expect even the most experienced of Git users will be able to take something away: perhaps a particular Git command or option they weren't aware of, or a new perspective on shaping useful revision histories.

Speaker justification

My experience working with many teams – on codebases old and new – has helped me appreciate the powerful detail we can lock away in our revision histories if we take the time. It’s shown me just how useful a well-considered history can be in, as well as the pain of a poor one. I’ve also been fortunate to work with some amazing developers who’ve helped me better understand and use the powerful tooling within Git. The last couple years I’ve been doing my best to spread these ideas and practices in the teams I’ve worked with. With this talk my aim is to distil this learning and understanding so it can be shared with a wider audience.

Edit proposal