I always find it amazing to see how different people create pull requests. Some people like to put every file they’ve touched into one big commit. Other people split their commits upper file. There are even people that split it up according to domains.

I’ve been all these people at one point in my career, but these days I’m all into atomic commits. Ever heard of that concept? No worries, let me introduce you to:

Atomic commits, sometimes also called micro commits, is the practice of explaining your thought process in the form of commit messages and code. It comes down to documenting the way to the solution.

An example is the easiest way to demo this.

atomicCommit.js

As you can see, pretty simple stuff: we get all the news items for the database and return some kind of view with the items.

Can you guess what happened to that file when you take a quick look at these commit messages:

That’s all pretty clear right. But you might still be wondering why we created those empty tests stubs first. This is what happens when we click those ...’s

This is the basic idea behind atomic commits: Small commits that tell a story.

The best way to do this by making the commits along with the coding of the feature. Look at a piece of code you have to write or refactor. You will start to see the things you need to do: first I have to create a file. Ok create the file, commit the file and explain why you need that file. Next, I need to create a method, create an empty method, commit. etc...

Yes, it is. I’m not going to lie to you, this is something you will have to actively do. But I assure you it will improve your workflow.

Atomic commits will drive the quality of your code reviews on pull requests way up. they will also understand your thought process, helping them to review the changes you made and keeping them motivated along the way.

I bet you’re not very stoked to start a review on this one:

This is not a very fun thing to do, you will also not get a lot of great insights on this. People doze off or lose track halfway through the review.

Not only will you get better code reviews, but you will also increase knowledge sharing inside the company along the way. If there are junior developers in the team, this can be a great tool to passively teach them some tips and tricks and even change their mindset on code.

They can fully see the workflow and thought process the committer made. And because a single commit is now a much smaller block of code everyone in the team can chime in and discuss the code.

This technique also has the great benefit of making cherry-picking in GIT easier. Mostly because you always have very small units to work with.

Atomic commits are not a new thing, they are even often described as a GIT best practice. Yet I don’t actually see them that often. People often either cite that it’s too much work (an excuse that seems to pop up on every good code practice thing), or that it will make their main branch too verbose (you can always GIT squash your commits before merging).

That said, I really hope you give this a shot. It might make your life and that of your team a little bit better. If not, you just have a feature that is a bit more verbose in your GIT history.

These days I’m all into atomic commits and it really made my work beter. Never heard of that concept? No worries, let me introduce you to it

Recently there has been a lot of commotion around code of conducts and if a user group/open-source project should implement them or not. This is not a post about that, we shall not be discussing the ethics or possible political impact this brings with it. We will however propose a starting point on how to implement them.

Please note that I am in no way an expert in this field, this blogpost is the result of endless talks with colleagues / friends and people I bugged on Slack (extra thanks to Paul Hallett and Jack Skinner).

So without further ado, I've made an easy 7 step program to follow along (this is the perfect time to fetch coffee or tea):

This is where the bulk of the drama comes from; most people are not really informed about what a Code of Conduct really is or start to overthink the concept. In essence it's actually really simple:

A CoC or a code of conduct boils down to a list of rules. These rules can be as verbose or short as you like, as strict or as loose as you like. It's just an outline of how people should behave when they attend your conference or contribute to your open-source project.

Lots of places have a code of conduct, like for example a bar, think "we don't serve people without shoes".

You might react with: "Well we've never had any problems before and I don't see the point in having one". Sure, don't adopt one. The world isn't going to end if you don't adopt one.

On the other hand a CoC can have the advantage that everyone clearly knows what's up. So if you turn into problems later down the line, you can easily refer to the rules.

Just make up your mind. As stated before, this post is not about whether or not you should implement one.

If you don't want to implement one, you can skip to step 7.

As always there is a lot of debate around this. You could if you want, but the general opinion is the same as on encryption, "Don't invent your own". Writing your own is pretty catchy (believe me, I've tried). There are lots of things to think about and frankly you probably want a CoC that's clear about its contents.

That's all good, but know that you'll be spending more of your time arguing about what passes as "Being awesome" then doing the thing you want to do. Holding conferences or writing code.

So if you want to save yourself some trouble and or time down the line, a good idea is to implement something that's already thought out and proven to work.

Luckily there are some easy ways to adopt CoCs out there, for example geekfeminism has a conference blueprint that can be used to roll your own: conferences CoC, if that one doesn't fit your bill there are others out there, for example: Conference Code of Conduct.

If you rather check out the codes of conduct of famous open-source projects/conferences and fit them to your needs, here are a few:

Google's Anti-Harassment Policy (template)

And there are a lot more out there. (If I forgot a major one, please contact me, or leave a comment).

So now comes the difficult part, choose one. This means:

Take one that you think fits your project/conference best.

Possibly adapt it to your needs. (if you adapt it, make it clear you've done so)

Please note that I don't want to favor one over the other, this is your choice here.

Ok, you've chosen your CoC. Now is the moment you want to share it with the world. Make sure you clearly show that you have a CoC and that you expect people to follow it. People can't follow a CoC if they don't know it exists.

You've chosen a CoC, or not, you've put it out there, we are done right?

Well no. Open-source is all about community. A project is never an island. There will be reactions on your decisions (if there aren't you should ask for them), now it's the time to discuss it with the community. Again, how you handle them is up to you, but it could be wise to be open to them (if you think they're good) and be willing to adjust some parts.

These things are like code, they can always be improved upon.

We shall not be discussing the ethics or possible political impact this brings with it. We will however propose a starting point on how to implement them.

Frederick Vanbrabant's

delirious rantings

Atomic commits: telling stories with git

How to implement a code of conduct