Cleanup Commits

You open a PR. It's not a big change, but there are a bunch of commits. Why so many commits? Let's take a look.

The first says,

WIP - first pass on this feature

The second commit says,

Implement feature x [ticket 123]

That is followed by a commit that says

lint

Then,

Fix broken test

Then,

Remove some comments

And then,

some formatting

Lastly,

Account for feature edge case

This is the real, honest path that many features take when we implement them. Our path to a feature meanders. It involves trial and error. We push some concerns out of our head while we do the main thing and then revisit them later. Though that is how we get there, it isn't necessarily the best thing to share with the team and commit to our main branch.

Most of these commits are what I'd call Cleanup Commits. These cleanup commits include things like:

• Recommendations from linting and formatting tools that we missed during our first pass on the implementation.
• Getting a test to pass that we didn't realize we broke with our original changes.
• Removing comments and logging statements.
• Precursor work like the WIP (work in progress) commit I included above. These often involve spiking out an initial take on the implementation, the exploratory part of coding a new feature.

Though all of these cleanup commits are part of the process of building a feature, they are not that useful in our commit history. When we think about the record of changes that we want to have written in the history books of our codebase, I'm not interested in, for example, a separate formatting fix. I'd rather just see the main commit with the correct formatting integrated.

By all means, use your feature branch as a scratch pad. Do what you need to do with your feature branch commits whether that is a WIP commit, a checkpoint commit, or a fixup commit. A lot of feature branches will have all of the above. All the segmentation doesn't need to live beyond the feature branch.

When the implementation is done and you're ready for a review, squash the relevant pieces together. Tell a good story rather than a literal accounting of events.