Subversion Best Practices Notes
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
andtags
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