On atomic commits and tiny PRs - the why & what helps me get there.

Today marks another day I've failed miserably at delivering a feature I have been working on for a while now. Not an easy one admittedly, with a lot of moving pieces, but regardless this time taking a different angle at it.

I am working on a PoC to integrate a new data source within the app I am building. Until today I had one story and one subtask in the dreaded swimlanes. It was all wrong, and took me way too long to realise there is an easy fix for that.

Divide and conquer.

Let me start with the anatomy of a Pull Requests and how its structure and content affect the Code Review process.

Pull Request anatomy:

• title
• description
• files changes
• conversations around it
• commits

Not a lot right? But surprisingly hard to get right. We've all been guilty of monster like the following:

Whenever I find, I've created one such I fall deep into the abyss of self-doubt. Especially when I can't make any sense of the energy & time that went into creating "IT". This may be a big reason for why I am on the hunt for tricks and rituals which will help me avoid succumbing to the lazy-bones part of my nature that wants to skip tough parts - namely communicating and being descriptive & concise.

What's the purpose of a PR:

• to tell your team that you're done / waiting on their input
• to propose a solution to the problem at hand
• to have a second set of eyes verify the validity of your approach (and fill you in on the context you're missing)
• to share context
• to make sure you're not missing out on some minute detail (or language quirk)

What's the purpose of a CR:

• provide feedback on the solution
• share context the author might have missed
• point out any technical errors
• understanding how something that can possibly affect your deliverable in the future works

The ideal we should strive to achieve - https://github.com/alphagov/govuk-puppet/commit/63b36f93bf75a848e2125008aa1e880c5861cf46 , someone better versed than my has dissected it before already, so I will spare you this remix -https://dhwthompson.com/2019/my-favourite-git-commit.

What strikes me every time I look at this example is how detailed it is. A seemingly simple change, has been massaged in a way to make the change easy to follow, understand and learn from for anyone reading through it.

Since we already know what we are going for - here are some tricks I've learnt which help me get there:

1. Divide and conquer - plan your work in tiny increments, then your Commit history can reflect your implementation plan
2. Use conventional commits - briefly mentioned before, the general idea is to use prefixes, such as : "feat" / "test" / "chore" / "docs" / "fix" etc. - they will help both you in separating your work into manageable chunks and your reviewers, letting them isolate particular changes from the rest of the code.
3. Use some form of ADR - a PR template is a great quick start. First - there is no tool overhead, you are just using what you were using anyway. Second - you get way more wins (think reminding everyone to write test and better code quality as benefit of the induced guilt of not testing) -  some great examples are here
4. Separate architecture & scaffold from implementation - that was learnt the hard way, while working with some of the cloud products. Some of the resource / stack changes will have to be separated to go through the deploys fine (think adding GSIs to DynamoDB - the side benefit of taking this approach are smaller PRs and more atomic commits.

Seems like it all comes down to planning and scoping down to the smallest possible change iteration. Always happy to hear about some new tools I should add to my arsenal on that topic!

An hour of planning can save you 10 hours of doing
-- Dale Carnegie

Extra talk on the subject:

Telling stories through your commits

A short talk sharing the key practices to make your commit history usefully document your code