How To Commit

How To Commit

Working with many people on a large project requires a thorough discipline (which admittedly is not easy to maintain) when it comes properly using a version control system. Additionally git, the VCS used by BALL, requires a mindset which is completely different from the ones required for CVS or SVN.

This guide explains some of the does and don'ts when working with the BALL source code (and other comparable projects). It assumes that you actually can properly handle the most common Git commands. If this is not the case take a look at the numerous tutorials on the internet.

1. Set up your environment

Well, actually there are only two important settings which need to be made by every git user:

• Her/His name
• Her/His email address

This can be achieved by issuing the following commands within the BALL source tree:

git config user.name "My Name"
git config user.email "email@address.com"

As petty as it might sound, doing this is crucial. Without proper and consistent naming it is nearly impossible to figure out whom to praise or blame for a certain changes and screws up almost every statistics git can create.

2. Stay up to date

This has two implications:

1. When working on your private repository make sure to fetch changes made by others on a regular (I recommend daily) basis. This can (for example) be done by:

   git pull --rebase my_remote my_remote_branch
   

   Note that when working with your private repository rebasing is recommended. However when you share your repository with others you should use merging, as otherwise your colleagues histories will be screwed up.

2. Try to keep your public branches small and topic specific. Creating branches is a very cheap operation in git. Try to merge include them back into master regularly. Merging is quite easy to do in git, however merging 2 years of diverging histories will still cause major pain. Techniques how to facilitate sticking to these advices can be found in the next few sections

3. Use branches

Branches are really a great way to organize one's work. However they need to be maintained properly because one tends to forget what this branch was good for. Going over your branches once every week, deciding which to keep, to delete or to merge, really helps with staying organized. Another thing branches are very useful for is to stabilize your commits: If you are not sure whether a commit is good enough, put it on a branch and test it there. Once you are satisfied with it git cherry-pick it to master. This is generally a recommended scheme: 1.If you are doing some work create a branch 1.Once you stopped working commit the results (even if you did not finish. Git allows to edit your commits) 1.Start working on another feature by checking out an existing or new branch. 1.If a feature (fix) is complete git cherry-pick to master 1.Rebase all your other branches to master

4. Do not push prematurely

Quickly fixing something and pushing it out to the central repository is a very tempting thing to do. Do not do this. From personal experience I can say that you overlooked something in about 70% of all cases. Make sure your commit compiles and links properly. (Beware! Sometimes only a make clean can reveal breakage.) Make sure there are no overlooked corner cases. Test your commits. On the other hand of course do not let a commit bitrot indefinitely. Once you are sure that nothing can go wrong fire away. If you are not, it can pay off to send a patch (obtained via: git format-patch) to other people for review.

5. Share bugfixes

Once you have fixed an annoying bug or compiler warning you can be pretty sure, that other people will thank you for this fix. There is no reason to let this commit bitrot in your monolithic development branch. In fact it will annoy the hell out of people when they discover that they have to merge two commits fixing the same thing. If you are not entirely sure whether your fix is correct: God gave thee a mouth to ask questions and two hands to write emails. Get some peer-review for your patches. (This also applies to small features which are not directly connected with the big feature you are developing.

6. Atomic commits

This is very important. When you do a commit, make sure it only contains changes which are related to exactly one topic.

• If you need a function in an already existing class: Create an individual commit.
• If you beautified some whitespaces: Create an individual commit.
• If you fixed a bug: Definitely create an individual commit.

On the other hand you should try to keep every commit self contained. It should not need an succeeding commit to make it compile, or work properly (as in, "before it did not do what it should have done"). This means that you should go over your commits with git rebase -i in order to squash unnecessary commits. However: Be smart about this. If the two commits are not of the style:

• Commit 1: Finished some feature
• Commit 2: Make the first commit behave properly you should not merge them. Especially if your patch is changing only whitespaces in a file (split the patch if it changes multiple files) it should always go alone.

When obeying these simple rules it becomes much easier to reorganize your commit history and especially to merge your code back into master.

7. Commit messages

It is sad, that this has to be said again and again: Write commit messages. At least write a short title that helps to identify what your commit did. ("Some bugfixes" does not. Where have which bugs been fixed?) Hoping that it will help (and knowing that it will not) let me employ the words of Linus Torvalds, the father of Linux and Git: Everyone who does not write useful commit messages "is by definition stupid and ugly" (Source: http://www.youtube.com/watch?v=4XpnKHJAok8)

8. Communicate

As already mentioned communication is a key to successful software development. Fortunately communicating these days is easier than ever before. There exist:

• Coworkers you can bother
• Mailing lists you can write to
• Bugtracking systems for filing tasks, defects and wishes
• Wikis for dumping your knowledge

You may safely assume, that people are interested in your work (if they are not, you have a different problem). Do not hesitate to write about problems, ideas, etc. If you stay constructive, it is more than likely that people will thank you for your hard work!

9. If you still mess around

This is no problem as long as you do it privately. Having other people work with chaotic commit histories or (even worse) unreadable, undocumented code is simply an impertinence. Forunately Git offers many tools which can be used to completely rewrite you commit history. Undoubtedly one of the most useful tools are

git rebase -i
git gui
gitk

It is strongly advised to look at your history and see if your commits can be tweaked. But you should also note, that editing a long and messy history again will cause major pain. The general rule is: The sloppier you are, the better you have to know your tools.