5 sins of subversion usage
Saturday, May 5th, 2007Whether you develop alone, or with others, there are some things that you should avoid doing when using subversion (or any other version control system).
1. Break the build and/or tests
The problem
It’s very common to break the build because you removed a class or changed a method contract. This can sometimes get frustrating. Others, who continue working on the project, will either have to tell you that you broke the build (thus asking you to fix it), or fix it themselves. This is something that requires communication and time. If more than one person fixes the problems, the possibility of conflicts is high.
Solution
a) Do a clean build and run all tests before committing. That is Shift+F11 and ALT+F6 in NetBeans.
b) Use a Continuous Integration system which does this for you.
2. No comments or bad comments
The problem
Examples of bad comments (yes, the first one is an empty string):
- uploaded Member.java
- Deleted some files
- Improvements
These comments are useless. Everybody can see from the log that Member.java was “uploaded”, or that some files where deleted. It is also not useful to say “improvements”, because it is very general, and also because it’s common sense that you are working on a project only to improve it (and not to make it worse).
Solution
Always write comments about changes in the software, and not about which files have been changed. Try to comment in terms of software modules, requests and bug fixes. You could even use issue numbers from your bug tracking software. Examples of good comments would include:
- Changed authentication to use cookies instead of the http session
- Changed from dbcp to c3p0
- First stages of html/css layout integration
- mock dao tests
- fixed mail scheduler (Issue 5532)
- Reporting engine now supports PDF export
One of the advantages of having comments such as the above is that you can easily select a range of dates and produce a change log.
3. Committing useless files
The problem
Some people commit stuff such as:
Sometimes Thumbs.db and _notes end up deployed on the production server. This is useless, bad and inappropriate.
Solution
Never commit stuff that should not be committed. Learn how to use the ignore/exclude patterns of your favourite svn client. In TortoiseSVN a the exclude/ignore pattern “thumbs.db _notes dist build nbproject” will do the job.
4. Not committing for days (or weeks)
The problem
A developer does not commit for days (or weeks) because he is lazy, always leaves from work in a rush, or hasn’t got a compiling application (for days… or weeks). Some reasons why this is very bad are:
- Code reviewer can’t review the code.
- Developer might be working on something that has already been done before, but nobody can tell him so.
- Developer might be trying to solve problem in a wrong way, but nobody can see that.
- Anxiety levels of Project Lead increases because he doesn’t know about work being done.
- Merging becomes really hard due to many (and difficult to resolve) conflicts.
- The possibility of completely loosing work increases as hard drives tend to fail when you least expect it.
Solution
Commit at least once a day. If you are working on a feature or fix that is completely unrelated with work that others do, consider branching.
5. Not following naming/structure conventions
The problem
When a repository is shared between many different people with many different projects, things can get messy:
svn://192.168.1.44/2006-playboy_website svn://192.168.1.44/COCA_COLA svn://192.168.1.44/JAVA-DEVELOPMENT/coca-cola-project svn://192.168.1.44/JAVA-DEVELOPMENT/coca-cola-project-DELETE_THIS svn://192.168.1.44/JAVA-DEVELOPMENT/coca-cola-project-static-layout svn://192.168.1.44/Project_1 svn://192.168.1.44/backup/Project_1 svn://192.168.1.44/backup/coca-cola-project-DELETE_THIS svn://192.168.1.44/dynamic site coca cola svn://192.168.1.44/important_docs svn://192.168.1.44/java-projects svn://192.168.1.44/java-projects/bar svn://192.168.1.44/java-projects/foo svn://192.168.1.44/java-projects/foo_1 svn://192.168.1.44/java-projects/foo_old svn://192.168.1.44/playboy_PROPOSAL_2002 svn://192.168.1.44/project1 svn://192.168.1.44/project1_ svn://192.168.1.44/οι εικόνες
Solution
Use naming and structure conventions. Make up your own, propose them in your team and adopt them. A possible convention could be:
- Only lower case in folders
- No native characters in folders
- Only dashes in folders (no spaces or underscores)
- Folder structure always uses root/account name/project name/project artifact
These simple rules greatly improve company’s xyz repository structure:
svn://192.168.1.44/coca-cola/dynamic-site/documents svn://192.168.1.44/coca-cola/dynamic-site/project svn://192.168.1.44/coca-cola/old-stuff svn://192.168.1.44/coca-cola/static-site/old-site svn://192.168.1.44/coca-cola/static-site/site1 svn://192.168.1.44/playboy/dynamic-site/community svn://192.168.1.44/playboy/dynamic-site/forum svn://192.168.1.44/playboy/dynamic-site/project svn://192.168.1.44/playboy/proposals svn://192.168.1.44/playboy/static-site/old-site svn://192.168.1.44/playboy/static-site/site1 svn://192.168.1.44/xyz/cms/project svn://192.168.1.44/xyz/cms/static-layout svn://192.168.1.44/xyz/interns/documents svn://192.168.1.44/xyz/interns/nick svn://192.168.1.44/xyz/interns/project-1 svn://192.168.1.44/xyz/interns/test-project svn://192.168.1.44/xyz/website/layout-1 svn://192.168.1.44/xyz/website/layout-2 svn://192.168.1.44/xyz/website/layout-3
Good luck.
Interesting reads:
- KDE SVN Commit Policy
- Version Control with Subversion