5 sins of subversion usage

Whether 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:

  1. Code reviewer can’t review the code.
  2. Developer might be working on something that has already been done before, but nobody can tell him so.
  3. Developer might be trying to solve problem in a wrong way, but nobody can see that.
  4. Anxiety levels of Project Lead increases because he doesn’t know about work being done.
  5. Merging becomes really hard due to many (and difficult to resolve) conflicts.
  6. 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:

  1. Only lower case in folders
  2. No native characters in folders
  3. Only dashes in folders (no spaces or underscores)
  4. 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

7 Responses to “5 sins of subversion usage”

  1. papo Says:

    I would also suggest the following. Adopt the SVN suggested repository project structure. such as /trunk
    /branches /tags . Develope in trunk do branches and tag the final releases. Everyone must be comfortable with the notion of the three of them. Checking out appropriate any of them or merging back to the tree!
    Do not import any project before creating such a project structure in the SVn repository!

  2. cherouvim Says:

    Yes, you are right.

    The SVN structure above displayed the paths up to the root of each individual project.

    Note though, that an SVN repo might not be used exclusively by programmers. Graphic designers might import static html/css templates in their own project folders. Enforcing this policy to them might not be for the faint hearted (no disrespect here).

    In any case, SVN, gives you the flexibility to work in any way you like.
    And when things get really messy, you can start renaming and moving things around. Then you simply send mails with the new locations where everyone can svn switch their working copies :)

  3. papo Says:

    your points above are for developers not….graphic designers…right? so …yes when it comes to developers ..they should stick to the recommended structure.or a strict defined structure known to the whole team

    .instead of sending multiple emails saying…Ooohhh yes by the way now you should download version from /aproj/thisversion/blabla . your ‘In any case’ scenario is NOT acceptable IMHO.

  4. cherouvim Says:

    Yes. They are for developers. But I just meant that sometimes the repo might be shared by other, less technical, people.

  5. ounos Says:

    /nbproject is actually required, unless you have a custom build script which is imported instead. Otherwise, how would one compile from the console? And how would one ensure that there is one standard build process (so not to allow much potential for the “works for me” syndrome)?

    Typically what is not needed is /nbproject/private (and causes problems, as it hardcodes file paths).

  6. John conrad Says:

    one more nice topic in your blog and nice comments too keep it up, If you advise some more related links to topic. I’m very interested in CMS and all its related subjects.

  7. Rob Church Says:

    Committing individual files one at a time, so that changesets are no longer atomic. This may or may not be detected even in a continuous integration environment; I caught this recently only by chance observation of a coworker who was checking in.

    It breaks one of the benefits of SVN, and it makes manipulating individual changes as “sets” harder than needed.

Leave a Reply

You must be logged in to post a comment.