Taming the cowboys: Commits
Commit: to promise or give your loyalty, time, or money to a particular principle, person, or plan of action:
Cambridge dictionary
Intro: the part you can skip:
I have the honor to work with an amazing team. Each one is totally different, with a different skillset, and is brilliant in his different way. One day I’ll dedicate a post describing them: The Woodpeckers and the Zitting, the Taurus, and the Bee. But one thing we all have in common: we all came from a cowboy programming background. And taming cowboys is not simple.
There is no need to explain the importance of coding standards, code review, or testing. But try to take a group of individuals that are used to commit a hundred lines of code at once, and code-review that. Good luck. But above that, enforcing a well-defined commit, force the programmer to think in a more structured, clear, and organized way.
This is why I gathered information about commit best practices. To have a solid understanding before throwing the lasso, and trying to taming down the gallop. Most If the practice is common sense. Still, there are some surprising and important issues that arose.
I’d rather see someone committing jibberish often than waiting 2 weeks to push up a perfect commit with the entire feature in one go.
ItsASine (Kayla)
Link to the “Cats & Commits” presentation slides.
Who cars about the commit?
You might ask who cares? As long as the branch represents the task, who cares about the internal steps that created it. And maybe, just maybe, if you are working in a hysterical startup, that doesn’t have the resources, but need to deploy fast, even on the cost of stability and the ability to maintain the product. Maybe you don’t. But if you want a stable product that will have a healthy and long life, you just can’t. And here are some reasons why:
Just note: This post address commits. Pull requests are a totally another issue, and will be handled in a separate post.
Commits best practices
Going over plenty of articles about “commit best practice” taught me two things: the first is that just like clean-code best practice, most of the recommendations are very simple and logical. Almost nothing dramatic or revolutionary. The second thing is that most articles copied one from the other. They even use the same jokes and examples.
Basically, there are five principles: Commit Small, commit often. Well defined and tight solid commented commits.
Commits small – commit often:
- Commits small
- Commit Often
- [Commit now, perfect later]
- Reduce check-out times
Well defined commits:
- Each commit has a single purpose
- Split changes into well-defined commits
- split the feature implementation into logical chunks
- Each bugfix should produce a separate commit
Commit tight:
- Never commit incomplete code
- Never commit just to have something before leaving the office.
- Don’t commit something that you “think” is completed
Commit solid:
- Commit well-tested code
- Commit code with no side effects
- Commit with none unrelated code
- Require code Reviews
- Test your code often, and commit once.
Never post comments that might cause a drama or emotionally hurt maintainers.
GitHub Etiquette
Comment as a short story:
- The comment should tell a story.
- A short story.
- In the present tense.
- That tells why this change has been made.
- Apply what the commit will do, rather than what you did: “If applied, this commit will …”
- Stop using bad commit messages like: “fixed a bug” / “changed a few things” / “removing method” / “more code refactoring” / “CFED-1234” / “add”
Oftentimes programmers working on something get sidetracked into doing too many things when working on one particular thing — like when you are trying to fix one particular bug and you spot another one, and you can’t resist the urge to fix that as well. And another one. Soon, it snowballs and you end up with so many changes all going together in one commit.
Sanket
With a good commit…
- It’s easier to read and understand the changes.
- It’s easier to maintain the codebase.
- It’s easier to find the relevant commit.
- It’s easier to reverse the relevant change.
- It’s more efficient to have code reviews.
- There’s less half-baked code.
- There’s less chance of side-effects.
- There’s less chance for bad code slip inside.
- There’s less chance of having merge conflicts.
- There is a better chance for a full testing suite.
- It’s easier to provide task estimation.
- It’s easier to track the work progress.
- It’s easier to split a task between IC’s.
- You must think in a more organized and structured way.
- In case you are hit by a falling piano, someone else can easily continue the task.
Don’t let tomorrow’s beauty stop you from performing continuous commits today.
Commits code smells
- Committing 100+ lines at once on a new file.
- Committing 20+ line changes on existing file.
- If it’s hard to succinctly the commit message.
- A timely commit routine: committing when you take breaks )i.e. lunch, end of the day, etc).
The commit treaty
In the process of taming the cowboys, I wrote down the commit treaty:
- Commit one change per commit.
- Commit only code relevant to the change.
- Commit code related to the change described in the message.
- Don’t commit bugs or broken builds.
- Don’t commit half-baked or uncertain code.
- Commit a clean code that meets style specifications.
- Commit with all the required tests.
- Write descriptive commit messages.
To sum it up, here is another definition of the term commit:
Commit: to send someone officially to prison or hospital:
Cambridge dictionary
Some of the more recommended resources and credits: