Blog

May 31, 2017

How to tackle the documentation problem

  • #tools
  • #git
How to tackle the documentation problem

At OSEDEA, we know one of the hardest things to do as software developers is documenting our code and keeping that documentation up-to-date is even more difficult.

The issue here is not that we don't want to document our code, we just don't think about it while we code.

This creates a situation in which we arrive at the end of a Sprint (or 2, or 3) and have done no documentation. And then, it hurts.

If it hurts, do it more often Martin Fowler

Even if this sentence usually applies to continuous integration, it is true as well for documentation. Introducing the task of documenting the code into our workflow is the solution we found at OSEDEA to tackle that problem.

Most of the time, it might add 5-10 minutes to document a new feature, but it is such a big win on the lifetime of a project that you will definitely win it back as soon as another developer has to onboard the project.

That's why, to simplify our everyday lives as developers, a member of the team created a tool to allow us to write documentation using the command-line, and that's where git comes into play.

Using git to structure your workflow

Git is amazing. Any developer who knows or learns about git

It is amazing for a lot of reasons, but today, I'm going to talk about automating some processes in your workflow.

Git offers a set of hooks that you can customize to modify your workflow.

Let's look specifically at the pre-commit hook.

Pre-commit hook

First, take a repository that you would like to try out on and setup your hook.

$ cd my-awesome-repo/

Your hooks are stored in each repository in the .git/hooks folder.

$ ls -la .git/hooks
---
total 88
drwxr-xr-x  12 osedea  staff   408 29 May 09:43 .
drwxr-xr-x  16 osedea  staff   544 29 May 09:44 ..
-rwxr-xr-x   1 osedea  staff   478  1 Jul  2016 applypatch-msg.sample
-rwxr-xr-x   1 osedea  staff   896  1 Jul  2016 commit-msg.sample
-rwxr-xr-x   1 osedea  staff   189  1 Jul  2016 post-update.sample
-rwxr-xr-x   1 osedea  staff   424  1 Jul  2016 pre-applypatch.sample
-rwxr-xr-x   1 osedea  staff  1642  1 Jul  2016 pre-commit.sample
-rwxr-xr-x   1 osedea  staff  1348  1 Jul  2016 pre-push.sample
-rwxr-xr-x   1 osedea  staff  4951  1 Jul  2016 pre-rebase.sample
-rwxr-xr-x   1 osedea  staff  1239  1 Jul  2016 prepare-commit-msg.sample
-rwxr-xr-x   1 osedea  staff  3610  1 Jul  2016 update.sample

Create a pre-commit file in .git/hooks

#!/bin/bash

exec < /dev/tty # Allows the script to ask input of the User
echo -e "\033[1;43mIs your Documentation up-to-date? (y/n)\033[1;0m" # The question the script will ask me, with a nice Yellow background color (see [this link](http://misc.flogisoft.com/bash/tip_colors_and_formatting) for more about that
read answer
if echo "$answer" | grep -iq "^y" ;then
    echo -e "\033[1;42mYou're so awesome!\033[1;0m" # Positive feedback and let the flow continue
else
    echo -e "\033[1;41mBad you!\033[1;0m" # Negative feedback
    exit 1 # Exit
fi

For your hook to be used by git, it needs to be executable, so be sure to chmod +x it!

Now try it!

$ touch test-committing
$ git add test-committing
$ git commit -m "This is a test"
---
Is your Documentation up-to-date? (y/n)
n
Bad you!
---
$ git commit -m "This is a test"
---
Is your Documentation up-to-date? (y/n)
y
You're so awesome!
[dev 3422755] This is a test
 1 file changed, 0 insertions(+), 0 deletions(-)
 create mode 100644 test

To remove your commit, just git reset HEAD~1 && rm test-committing

I am not going to talk about it today, but know that the post-commit hook can be very useful as well, and works exactly the same way.

Global installation

As of git 1.7.1, you can set init.templatedir in your gitconfig to tell git where to look for templates.

Set it like this:

git config --global init.templatedir '~/.git_template' Afterward, new repositories you create or clone will use this directory for templates. Place the hooks you want in ~/.git_template/hooks. Existing repositories can be reinitialized with the proper templates by running git init in the same directory .git is in.

For git versions older than 1.7.1, running git init --template ~/.git_template will work if you're like me and still want to manage your .git_template dir along with the rest of your dot files. You can also use the $GIT_TEMPLATE_DIR environment to tell git init where your template directory is. Thank you, Stackoverflow Users! (source)

Move your pre-commit script into your newly created ~/.git_template/hooks folder and test out if git is getting it:

$ # Still in the `my-awesome-repo/` folder
$ mkdir -p ~/.git_template/hooks
$ mv .git/hooks/pre-commit ~/.git_template/hooks
$ git init
$ cat .git/hooks/pre-commit

You should see your hook there, brought back by the git init, and it should be there by default in any new or cloned repository thereafter!

Conclusion

Git hooks are very powerful and I think they can be used to make everyone in the team more efficient. You can do whatever you want in them, including, running your tests, your linter, etc. Finally, if you need to push a really important fix in production right now and don't have the time to worry about documentation or linting, do not worry, you can always skips the hooks with git commit --no-verify.

I hope you liked this article, feel free to share it, comment below to give us feedback or kuddos. :)

Adrien Thiery