What are some of the best SCM practices?

Question

I have been using Git for some time now to manage my own personal projects. I didn't really think about how I used it. I usually commit all the changes whenever there is a milestone not really thinking.

But after reading a blog post that mentions how you should right your commit messages, I realized that I don't really know how to properly utilize SCM.

So I am wondering if you have any tips regarding things like:

• When you should commit a change
• How to write the commit message
• How to work with others using a repository
• anything else...

Thanks!

Answer 1

I generally commit after a new feature has been added, or after a documented bug fix has been completed. Basically, one thing at a time. This makes it easier to rollback changes.

As for the commit message, I'll list the added functionality for a new feature. For a bug fix, I include the ID of the bug from our bug database.

Answer 2

When you commit a change make sure that the code builds and is basically functional. It's bad form to commit code which breaks the build. If you are working in a team environment there is nothing worse than checking out the latest code to find that it breaks the application or doesn't even compile.

As regards to comments, give a rough description as to what the code does and ideally why you have done it. this enables you to figure out what a check in does without having to read the code

Answer 3

For personal projects I tend to make commits as often as practical, which can be a couple of times an hour as this allows me to go back in time to a previous "snapshot" when I realize I have been going down the wrong route.

For multi-user projects it will depend on the rules, you can't commit something until you have attained those targets. Personally I tend to commit when I can write a comment along the lines of "fixes this ticket" or "implements this functionality".

As for comments, I put a summary of changes or a ticket or wiki reference. The code and thus the diff should be documented enough to give details.

Answer 4

Check out Source Control HOWTO from Eric Sink. The last time I went through it, it was focused mostly on centralized VCS, but there are still lots of good things in there.

Answer 5

When working on a small personal project, it probably matters less because you know your code, you remember what you have done, approximately when etc - at least I do.

But for bigger projects with many developers, it is imo important to

• Always specify issue number (can be enforced with any good SCM)
• Keep number of commits down
• Only commit working code
• Only commit code that is better than the code was before
• Commit clean code (i.e. dont leave test code, old commented code etc behind)
• Write not only "fixed issue X" as comment, but stating more info about the bug/changes, for example "fixed issue X, where panel would expand beyond window size".

When looking through the history of changed files and you are trying to find out when a a particular problem appeared good comments will help you find the right commit much quicker.

By keeping number of commits down, it will also be easier to check changes related to a new feature, revert a "feature" or merge it into another tree.

/B

Answer 6

I'm aware of two defensible and commonly practiced uses of the power to commit:

• Fine-grain commits, where you commit early, commit often, and in small chunks. The system may not be in a good state at every commit. The major benefit of this practice is that you get a very clear view of what has been changed and when, and with a system like darcs or a command like git-rebase you have a chance at "cherry picking" commits that interest you.

• Reliable commits, where you commit only when the system is in a solid state, e.g., it not only builds but also passes regression tests.

In a large group project, some sort of reliable scheme is a necessity, although you can still do fine-grain commits locally and make them public only when in a solid state.

After many years I have observed consistently that most students and other beginners are afraid to commit and don't commit often enough. For my own projects I tend to use the fine-grain approach, and for larger projects I typically carry at least two branches, doing solid-system commits on one and fine-grain commits on the others.

Answer 7

The other answers are good for working with a central repository used by multiple people. When I use git, I usually have my own private branches for the stuff I'm working on, and I tend to make lots of small commits. When developing I find this is useful as I can quickly backtrack when I realize I should have done something differently, and I also have a relatively detailed log of what I have done.

Then when I'm have something ready to push upstream (i.e. tested, documented etc.) I push as a single commit, avoiding clutter in the central repo. Best of both worlds.

Answer 8

Since you're using git, here are some of my practices that may or may not work for you:

1. Always work in a local branch with descriptive names, say work/feature_name (using the awesome bash completion for git to help you type)
2. Commit as often as you want in local branches with terse comments (to document intentions for reminding yourself.) So you have the complete original thought/development history that you can go back to.
3. Before you push/publish commits/patches, create a pu (proposed updates) branch (git checkout -b pu/feature_name) from your work branch and use git rebase -i to make perfect commits, i.e., group related small commits (and/or split large commits) in to logical commits and write meaningful descriptions (for others and yourself) make sure each logical commit builds and passes regressions.
4. Publish your pu/feature_name (either ask people to pull or just push to a public server like github.)
5. It's likely you'll need to iterate through 3 and 4 a few times if you have a code-review process.

It sounds complicated, but it's really a joy to practice (at least for me), as git is so fast and feels so right in doing all these steps.

Answer 9

• Commit early, commit often.
• Keep the commit small. If the commit is large, try to break it down where it makes sense.
• Don't break the code. Each commit should keep the code in working condition.
• Try to include the intention in the commit message instead of only the "what".
• Don't comment out codes. Remove them instead.
• Make use of the branch for experimental or potentially code breaking changes.
• Tag your shipped version.