SVN best-practices - working in a team

I'm starting out with SVN. I know the basic commands and understand the base principles. I was wondering if anyone has any tips or best practices for working with Subversion in a team environment.

I can see the benefit of adding reasonably verbose messages when committing code, but are there other things I should bear in mind?

Thanks for all the great answers - they've helped a lot.

Encourage frequent commits. Teammates new to version control may feel like they need to keep the code out of the repository until "it works right". Teach everyone to commit early and often to find issues as soon as possible. Instead of holding code 'till it works, propose that your teammates create branches for feature that might break trunk. That leads to...

Establish a branching and tagging practice. In addition to branches for features, encourage your teammates to use branches for large-bug fixes. Tag major bug fixes at the beginning and end of the work. Maintain tags (and possibly branches) for production/qa releases.

Establish a policy for trunk and stick to it. One example might be, "trunk must always build without errors." or "trunk must always pass all unit tests". Any work that can't yet meet the standards of trunk must be done in a branch.

Do not commit formatting changes with code changes

If you want to restructure a giant file's whitespace (Control+K+D), fine. Commit the formatting change separately from the actual logical change. Same goes if you want to move functions around in files. Commit the moving separately from the actual editing.

One of the key concepts I always stick by is to commit related code changes together. The corollary is do not commit unrelated code changes in the same commit. This means don't fix 2 bugs in one commit (unless it's the same fix), and don't commit half a bug fix in each of 2 commits. Also, if I need to add some new enhancement or something to an unrelated part of the system that I then need for some other work, I commit the enhancement separately (and first). The idea is that any change anyone might conceivably want to have on its own (or roll back on its own) should be a separate commit. It will save you tons of headaches when it comes time to do merges or to roll back broken features.

A lot has been mentioned already, and here are some more:

1. If you have files that you don't want in source control (e.g. configuration, compiled files, etc.), add them to the ignore list. This way you notice any files that you forget to add by always expecting an empty list of files showing as unknown to SVN.

2. Add a post commit event that would send an email to your developer mailing list (or a one specific for this target) relating to the committed change and ideally the patch for it.

3. Integrate with your bug tracker so that references to commits show up on the bugs / feature requests with links to the diffs. Bug trackers like MantisBT support this.

4. Consider integrating with continuous integration (e.g. CruiseControl.NET), NAnt for Build, and NUnit/VS for unit tests. This way once a user check-ins code or on a scheduled interval the code gets compiled, unit tests are run, and the developer gets feedback of the process. This would also alert the rest of the team if the repository is broken (i.e. doesn't build).

Well, the basics:

• Create tags before starting QA on a version
• Create tags before risky changes (i.e. big refactors)
• Create branches for released versions in order to freeze the code.
• Make sure that people know to update before starting work on a piece of code and update once again before committing it.
• SVN allows multiple check outs of the same file by different users. Make sure that everyone resolves any conflict that may occur.
• Never use the same SVN account for more than one user. Terrible things may result.

The answers that people are giving are great. Much of this is summarized in the svn user doc for best practices for SVN.
To repeat:

1. Set up your repository structure (you should have project root with trunk, branches, and tags underneath)
2. Choose your policy re branching (private branches, branches per milestone/release/bug, etc) and stick to it -- I'd recommend more branching rather than less, but no need for private branches
3. Choose your policy re tagging -- more tags the better, but most importantly decide on your tag naming conventions
4. Choose your policy re committing to trunk -- keep trunk as "clean" as possible, it should be release-able at any time

I would like to summarize best practices I stick to:

1. Do not commit binaries. There should be separate repository for binaries, such as Nexus, Ivy or Artifactory.

2. There should be repository structure. Personally I use following repository structure:

   /trunk
   /tags
       /builds
           /PA
           /A
           /B
       /releases
           /AR
           /BR
           /RC
           /ST
   /branches
       /experimental
       /maintenance
           /versions
           /platforms
       /releases
   

3. Use specific list of branch types. My list is following: experimental, maintenance, versions, platforms, releases.

4. Use specific types of tags: PA (pre-alpha), A (alpha), B (beta), AR (alpha-release), BR (beta-release), RC (release candidate), ST (stable).

5. Minimize necessity of merging. There should be rules when merging is possible/encouraged and when it is not.

6. Version numbering. There should be established version numbering approach to stick to. Usually it is described in such document as Software Configuration Management Plan, it is a part of high-level project documentation. Personally I use complex version numbering approach. According to this approach, versions have following patterns: N.x.x (maintenance/support branches), N.M.x (release branch), N.x.K (build), N.M.K (release).

7. Commit as frequent as possible. If it tends to be difficult (for example, when there should be too many changes to be made in order to implement feature and even compile code), experimental branches should be used.

8. Trunk should contain the latest development. For example, when there is a choice where to develop new major version (N.x.x) of application, in trunk or in branch, decision should be always made in favor of trunk. The old version should be branched into the maintenance/support branch. It assumes that there is a clear distinction between major versions and their specifics (architecture, compatibility) emerges as early as possible.

9. Strict 'do not break the build' policy on release branches. In the meantime, it should not necessarily be strict for trunk as long as it might have either experimental development or codebase which needs merge issues to be resolved.

10. Use svn:externals. It will allow to modularize your project, establish transparent release management procedure, divide and conquer over different functionality.

11. Use issue tracking. You will be able to point out the issue reference inside the commit message.

12. Disable empty commit messages. It could be done using pre-commit hooks.

13. Define which branches you want to continuously integrate. For example I prefer using continuous integration for trunk, maintenance and release branches.

14. Establish continuous integration policy for different types of branches. As I pointed out earlier, most strict "don't break the build" rules apply to release branches, while trunk and maintenance branches might be broken sometimes. Also there is difference between list of inspections run on the trunk/maintenance and release branches.

You can find outline of my subversion best practices in the form of diagram illustrating main principles of software configuration management approach I use.

One thing I've found very useful is the svn:external property which means you can reference directories from other repositories into your own. It's gives really nice ways of organizing your code and data. Some examples are:

1. If you have a separate repositories for code different modules/libraries and reference in the ones you are using. This means that you can have a meta repository for every executable. If it's a small executable that only uses a few modules, you won't need to checkout the entire tree. An effect of this is that you get SVN revision numbers per module.
2. Adding large binary data such as compiled versions of libraries to code repository is generally considered a bad habit, but it can be really convenient. If you just add all versions of all libraries you use to a different repository you can get the best of two worlds. You reference in the versions of the libraries you use into your code repository. When checking out your code repository you'll get both the code and the binaries as well. However the binaries are stored in a large repository which you don't need to backup as rigorously as your source code and the source code repository stays small and contains only text.

Use integration with your bug tracking software. If you use Bugzilla, you can set it up so if your comment begins with "Bug XXXX" your SVN comment is automatically added as a comment to the given bug, including a link to you SVN web interface to that revision.

Learn about SVN's branching and merging tools and conventions.

The best way to work with other team members is to break work up into complete development features/fixes, then work on individual changes, each in a branch. Then merge the changes back to the mainline branch/trunk when completed/ready/approved to be merged in.

This way individuals can work towards a common goal (either on the same branch or seperate branches) without colliding with other changes.

Your mileage may vary, and this may be overkill for only two or so people.

It makes it much easier if you're using good tools that integrate well with SVN. These make it easy to see what's been changed and to then commit all or part of your changes and to frequently update your working copy to the latest version in SVN.

I recommend Tortoise SVN (If you're using Windows) and Visual SVN (if you're using VS).

Also see if you can set it up so that you get e-mail or similar notification any time a change is committed (usually also including the commit message and a list of changed files). Services like CVSDude offer this. I find it helpful to know both that an update has been made and then to have some idea of what's contained in that update before updating my working copy.

The golden rule for source control: Check In Early, Check In Often

For tips how to organize your repository:

• How do you organize your version control repository?
• SVN Book Chapter 5. Repository Administration
• Repository layout

Besides branching policies et al. (where one size does definitely not fit all), you should have good commits:

• The commit should relate to a single piece of work if possible; a bug fix, a new feature- there should be some 'logic' to what changes you committed
• The commit should have a descriptive comment that will help you locate it browsing the repository history. Most people suggest writing a single sentence at the beginning that describes the whole commit and a more detailed account below
• If possible, you should tie the commit to your bug-tracking system if possible. Trac, Redmine et al. let you create links from bugs to commits and vice versa, which comes in very handy.

Consult with your team about their changes, or at least look at the diff very carefully, before fixing any merge conflicts. Ask them to review the merged code themselves to make sure their additions were not lost in the merge.

One thing that I have seen that reduces broken commits is to have good pre-commit scripts. For example, you can run any unit tests before the change is committed. This will cause commits to be a little slow, but you save time by avoiding stepping on someone's toes and having to apologize. Of course this becomes a lot harder to manage when you have a large development team and very frequent commits.

One of the examples of integration with bug-tracker and commit policy enforcing could be Trac's svn pre/post-commit hook scripts, which can refuse commit if commit message doesn't reference any ticket in bug-tracker and add comments to existing tickets based on message contents (i.e. commit message may contain something like "Fixes #1, #2 and #8", where #1, #2, #8 are the tickets numbers).

Best practice to use SVN:

1. When you first came to office and open your Eclipse project, the first step has to be done is to update your project.

2. After taking update, start your work. When you finished your coding, check it properly, whether your application runs properly without any exception. Once you are sure about your code is working fine, it's time to commit the code.

Note :While committing the code, don’t commit directly. Make a synchronization with server and check what are all needs to be committed. Note: Don’t commit the whole folder once. Because you may have done some changes to file for your requirement or you may have deleted some files in your local system. But the settings are different on the server. So check the files individually and commit the code.

3. Don’t commit/update conflict files directly.

4. When to do override and update?

   When you are pretty much sure that you don’t need any of your local changes and want to update the server copy completely. Note down that once if you do the override and update, you will not get any of your local changes.

   Note: Don’t keep the project without updating for more than a day. Also don’t keep the code without committing for many days.

5. Communicate who are all working in same component and discuss what changes they have made every day.

6. Don’t commit the properties and configuration file unless there is some reason. Because the settings will be different on a server and in the cloud.

7. Don’t commit target folders into SVN, only source code and resource folders has to be maintained in an SVN repository.

8. When you lost your code, don’t panic! You can get back the earlier copy from the SVN history.

9. Don’t checkout the project into multiple places of your disk. Checkout it in one location and work with it.

---

SVN by itself is a good start and some of the other posters have offered some great suggestions on best practices.

The only thing I would add is that you should be hooking up SVN with CruiseControl or TeamCity to drive a Continuous Integration process. This will send out build emails and let everyone know when someone broke the build.

It will be very telling early on who's following your process and who isn't. Might lead to some friction but your team will be better off in the long run.

• Precise comment for every commit

• Don’t break the (mainline) build!

• Commit as soon as a logical unit changes

• Avoid using Subversion as a backup tool

• A little branching/merging as possible

.

More details can be found in SVN best practices.

Use this for the comments template:

[task / story xxx][minor / major][comment][follow up comment][URL to bug]

Do DEV work on Branches

1. Frequent commits to your branch
2. Discrete/Modular commits to your branch (see here)
3. Update/Merge-from trunk often. Don't sit on your branch without re-basing

Community Trunk

1. Should always build/work
2. One issue per commit (again see here) Mostly so you or others can back-things-out one at a time
3. Don't conflate refactoring/whitespace changes with logical changes. Your teammates will have a tough time extracting what you actually did from a commit

Remember that the more incremental, modular, discrete and succinct you make your commits, the easier it will be for you (or likely others) to:

• Incrementally back out changes
• Visually realize what you actually did without sifting through tons of white space and variable name changes.
• The commit messages mean more when the ratio of work done to message length is lower.