SVN user guidelines

Question

I have been tasked with writing a set of user guidelines for SVN for developers in my company.

The guidelines are to be solely from a user perspective (e.g. commit comments, when to commit) and not from an administrative perspective (e.g. when to tag, how to structure). An administrative guideline will be written in a separate document.

We are an app development house involved also in embedded development. So our developers range from HTML5 and Flash to Java and C. Some of our coding involves forking very large (millions of files) code bases. Other parts involve us engaging in ground-up development.

Are there any best practices for use of SVN from a user (i.e. grunt developer) perspective?

Answer 1

This is a fairly subjective question, so I wouldn't be opposed to TPTB closing it. However, I'll happily share my opinions on this. Keep in mind that I come from a background working in small/medium (10-50 developers) enterprise contexts, so my opinions are tailored to that environment.

1. Your developers should understand subversion. Have them read the subversion book, especially the "basic work cycle" bit. Many of my other suggestions come from the svn book.
2. Commit early and often. Developers should strive to do work in small chunks that are not breaking or destabilizing. If you aren't checking in your work at least once a day, something is probably wrong.
3. Update extremely often. You want to pull the latest work the rest of your team has been doing multiple times a day. This also helps ease the pain of merging changes in the event that another developer is working on the same files.
4. Always provide a useful comment. Developers should write check-in comments that describe the work done in a way that is helpful to the rest of the team. Comments like "fixed build", "more changes", or "x" (true story, I worked with a developer whose comment was always "x") are not useful.

The following are more "admin" guidelines (in your taxonomy), but are still relevant to developers. Also, these are much more subjective, so take with an even larger grain of salt.

1. Maintain a stable, releasable trunk. If your developers are following guideline (2) above, you should be able to keep your trunk stable and releasable. Avoid making large, cross-cutting, destabilizing changes -- figure out a way to make those changes in small chunks that are less risky. Maintaining a stable trunk allows you to deploy more frequently, and therefore deliver value to your users faster.
2. Use the branch-per-release workflow. Create a new branch for each release in the event that you need to fix bugs. Avoid releasing from trunk or "promoting" from trunk into a static release branch.
3. Avoid feature branches. Feature branches encourage the kind of destabilizing, cross-cutting changes you want to avoid. Instead, try to make large-scale changes in trunk, but keep them "deactivated" in the production software via configuration switches or the like. You want to strive for an architecture that allows you to implement "big" features without the need to destabilize and isolate the code line. Using Inversion of Control is a big help here.

Answer 2

To supplement @Stuart Lange's great suggestions, here is my list that I have been honing for some time. This comes from both my experience and my research for my TortoiseSVN and Subversion Cookbook being serially published on Simple-Talk.com (part 8 was most recently published with more to come). For brevity I am listing only the bullet items here--my series of articles provide rationale and support for all of these in great detail.

A. Each commit should be for a single reason.

B. A single reason should be committed all together: code, help file, db schema, etc.

C. A commit should never break the build.

D. Always have a reason to commit a file.

E. Always review what you are about to commit, line by line.

F. Make commit messages required.

G. Commit in a timely fashion.

H. Do file operations (move, copy, rename) within your version control system as much as possible.

I. Include everything in source control except your generated files (so do include 3rd party binaries).

J. Never do a commit in isolation: consider SVN update/manually verify/SVN commit as an "atomic" operation.