These are notes from a webinar on Subversion best practices, conducted Aug. 30, 2006 by CollabNet. Now that I’ve cleared the cobwebs from this blog, I’m posting them here for future reference.

Presenter: Garrett Rooney, author of Practical Subversion, and a Subversion project committer.

Two organizational strategies: unstable trunk vs. stable trunk:

Unstable trunk

  • Development occurs in unstable trunk
  • All developers are exposed to your changes immediately, so find problems faster

If you use unstable trunk, here’s what helps make it work:

  • Atomic commits (one change does one thing)
  • Developers who pay attention by watching what gets committed

Stable trunk

  • In stable trunk, you develop on branches and merge it back into the trunk when stable
  • Bugs don’t disrupt people as much, but bugs don’t get exposed as fast
  • On big teams, you could prefer a stable trunk because a bug committed to trunk could inconvenience hundreds of people. An alternative is to have each team work in their own unstable trunk.

Best Practices

  • PREFER an unstable trunk when possible

    Getting more eyes on change is a good thing. If you have good tests, people unlikely to commit serious problems into trunk.

  • For each project, create a trunk, branches and tags directory
  • Branches are copies of the trunk stored in the “branches” directory
  • Same with tags
  • This is just a convention, but good because people are used to it

  • Encourage frequent, small commits
    • If it doesn’t get committed, it doesn’t exist
    • Avoids lost code due to disk failure, accidental deletes
    • But you need to be confident your changes won’t break things. Good tests help here
    • Each commit should target one goal
    • Prefer smaller changes — each change done for one goal
    • Makes changes easier to understand, and simplifies merging between branches.
    • Goal is to optimize changes for understandability
    • Make sure people understand the change:
    • What did you change
    • Why did you change it?
    • What files and functions modified?
    • That way, can search change logs for specific functions

    • Write good commit log messages
    • Keep log message in your head if small changes
    • Write log messages as you go
    • Tools to simplify: tools/dev/svn-del.el (emacs macro)
    • Tests are critical for unstable trunks
    • Good tests that all developers can run will help
    • Create a culture where breaking tests is just as bad as breaking build
    • Consider test-first development
    • Commit notifications should go to all developers
    • Developers need to know what changes are being made
    • Use post-commit hook script to email changes
    • Use project-specific mailing lists
    • Email notification makes it harder for people to ignore changes
    • Creates forum for review, discus pros/cons of changes
    • Avoid branching when possible
    • But don’t be afraid to branch when it’s needed</ul> Branching

    Use branches when:

    • Long-term refactoring that will breaks things
    • New modules that won’t work for some time
    • Release branches
    • Long-lived development branches
    • Experimental branches

    Branch risks:

    • Creates extra work because you’ll need to merge
    • Divides developer attention by separating code bases
    • Means you have to worry about merging changes
    • Avoid branching when possible

    Reducing pain of branches:

    • svn doesn’t track merges (yet).
    • Remember when you branched
    • Record what you’re merging whenever you commit
    • Tools like svnmerge.py can help. We use it on svn project to automate merges
    • Keep branches short-lived: changes are fewer, merges easier
    • Regularly merge back from branch to trunk
    • Don’t make gratuitous whitespace/formatting changes It makes merges harder later on