RepositoryStructure

Version Numbering

SqueezeCenter releases will follow a three-number versioning system, such as "7.0.0". The first two numbers comprise the major release number, and the final number is a minor release number. Generally speaking, the first number will increment on major architectural changes, the second number will increment for feature releases, and the third number for bugfixes of a given feature release. All version numbers start counting at zero.

Repository filesystem and branching structure

The top-level URL for the SqueezeCenter repository is: http://svn.slimdevices.com/repos/slim/

Underneath this directory, the next level of structure is a set of directories which correspond to major release numbers (feature releases), such as "7.0", "7.1", etc. Underneath these version-numbered directories will be the usual subversion-style "trunk", "branches", and "tags" directories.

In terms of SVK copy (branching) operations, the major release trunks branch downwards from each other in version order. That is to say, 7.0/trunk is the root of the repository, 7.1/trunk is a branch from 7.0/trunk, 7.2/trunk is a branch of 7.1/trunk, and so-on. Then within each major release subtree, any branches in branches/ are branches of the corresponding trunk. Similarly, any tags within the tree are branched from the corresponding trunk.

Release version tags are considered to be read-only branches. These are a record of what was released as that version number, not a place to commit any kind of work.

This can be difficult to follow, as there are effectively two independent, parallel tree structures going on here - one is the directory tree structure, and the other is the branching tree structure. Here's some visual layouts to make the picture clearer:

Filesystem layout:

slim    
  |---7.0    
  |    |---trunk    
  |    |---branches    
  |    |       |---a_feature    
  |    |       |---big_feature    
  |    |       |---something_else    
  |    |---tags       
  |            |---7.0.0    
  |            |---7.0.1    
  |            |---7.0.2    
  |---7.1    
  |    |---trunk    
  |    |---branches    
  |    |       |---cool_feature    
  |    |       |---another_one    
  |    |---tags    
  |            |---7.1.0    
  |            |---7.1.1    
  |---7.2    
  |    |---trunk    
  |    |---branches    
  |    |---tags    
  |---7.3

Branching layout:

slim/7.0/trunk
   |---slim/7.0/branches/a_feature
   |---slim/7.0/branches/big_feature
   |---slim/7.0/branches/something_else
   |---slim/7.0/tags/7.0.0
   |---slim/7.0/tags/7.0.1
   |---slim/7.0/tags/7.0.2
   |---slim/7.1/trunk
           |---slim/7.1/branches/cool_feature
           |---slim/7.1/branches/another_one
           |---slim/7.1/tags/7.1.0
           |---slim/7.1/tags/7.1.1
           |---slim/7.2/trunk
                   |---slim/7.2/branches
                   |---slim/7.2/tags
                   |---slim/7.3/trunk

This branching layout makes it easier to manage the whole tree via SVK push and pull operations.

(thanks to Tree::Simple::View::ASCII for generating the diagrams above)

Commit Policy (what gets committed where and when)

Bugfixes should be applied to the earliest trunk affected, and SVK will be used to propagate the bugfix downwards to the later trunks (and their branches). SVK push operations will be used to merge feature branches back to their respective trunks only. There are no pushes from newer trunks back to the parent trunk.

If a bugfix is accidentally applied to a later trunk than it should have been, someone will need to manually re-apply that diff to the correct trunk and then pull the change through again. SVK should resolve the duplicate change ok in most circumstances.

New features that are small in scope get committed to the appropriate trunk for the version they are targeted for. Larger features requiring more extensive work and possibly temporary breakage should be in their own feature branch. Feature branches must be created and managed via SVK, not the normal subversion client.

Most developers will only need a regular subversion client and a checkout of the appropriate "trunk" for whatever version they are working on. We will handle scripted regular "svk pull" operations to keep everything in sync in the repository. If, however, you're working on a feature so big that it needs its own branch, you will need to create and manage the branch with SVK, not regular subversion.

Version lifecycle

When working on features for a new, unreleased major version, the commits go into the appropriate trunk and/or branches as noted above. As development of this new major version draws to a close and we switch into bugfix-only mode, obviously any newer features must target later versions. Any outstanding feature branches at that time which didn't make the cutoff for the version about to be released will need to be manually moved to be feature branches of a later version. This is done by taking a branch diff and using it to create the new branch via SVK.

Once the initial release for a major version has been made (tagged as x.y.0), the trunk for that major release series is definitely for bug fixes only, and will be used to generate further minor-version bugfix release tags in that series (x.y.1, x.y.2, etc).

Of course the definition of terms like "bugfix" and "feature" are up to managerial discretion and real world constraints.

Jive

The Jive repository will be structured and used similarly to the above, but lives of course at http://svn.slimdevices.com/repos/jive.

SVK Information

This is a good guide to SVK for Subversion users: http://www.newartisans.com/blog_files/svk.primer.php

This is the SVK Home Page: http://svk.bestpractical.com/view/HomePage