When should a multi-module project to split into separate repository trees?

Question

Currently we have a project with a standard subversion repository layout of:

./trunk
./branches
./tags

However, as we're moving down the road of OSGi and a modular project, we've ended up with:

./trunk/bundle/main
./trunk/bundle/modulea
./trunk/bundle/moduleb ./tags/bundle/main-1.0.0
./tags/bundle/main-1.0.1
./tags/bundle/modulea-1.0.0

The 'build' is still quite monolithic in that it builds all modules in sequence, though I'm starting to wonder if we should refactor the build/repository to something more like:

./bundle/main/trunk
./bundle/main/tags/main-1.0.0
./bundle/main/tags/main-1.0.1
./bundle/modulea/trunk
./bundle/modulea/tags/modulea-1.0.0

In this pattern I would imagine each module building itself, and storing its binary in a repository (maven, ivy, or another path of the subversion repository itself).

Are there guidelines or 'best-practices' over project layouts once one goes modular?

Answer 1

The Subversion book contains two sections on this:

• Repository Layout
• Planning Your Repository Organization

A blog entry on the subject: "Subversion Repository Layout"

The short answer, though: while your mileage will vary (every situation is individual), your /bundle/<project>/(trunk|tags|branches) scheme is rather common and will likely work well for you.

Answer 2

This is very much up to personal preference, but I find the following structure suitable for large projects consisting of many modules:

branches
  project-name
    module1
      branch-name
    module2   
      possibly-another-branch-name
    branch-name-on-a-higher-level-including-both-modules
      module1
      module2
tags
  ... (same as branches)
trunk
  project-name
    module1
    module2

I have also often used the structure in large repositories containing many projects, because keeping all projects in the same repository makes cross-referencing projects and sharing code between them—with history—easier.

I like to use the structure with root trunk, tags and branches folders from the start because in my experience (with large repositories containing many projects), many sub-projects and modules will never have separate tags or branches, so there is no need to create the folder structure for them. It also makes it easier for the developers to check out the entire trunk of the repository and not get all the tags and branches (which they don't need most of the time).

I guess this is a matter of project or company policy though. If you have one repository for each project or a given developer is only likely to work on a single project in the repository at a time the rooted trunk may not make as much sense.

Answer 3

Just my two cents...

I just want to emphasize the comment in the SVN documentation (already quoted in another answer, same thread) http://svnbook.red-bean.com/en/1.4/svn.reposadmin.planning.html#svn.reposadmin.projects.chooselayout

The excerpt references the following structure : / trunk/ calc/ calendar/ spreadsheet/ … tags/ calc/ calendar/ spreadsheet/ … branches/ calc/ calendar/ spreadsheet/

"There's nothing particularly incorrect about such a layout, but it may or may not seem as intuitive for your users. Especially in large, multi-project situations with many users, those users may tend to be familiar with only one or two of the projects in the repository. But the projects-as-branch-siblings tends to de-emphasize project individuality and focus on the entire set of projects as a single entity. That's a social issue though. We like our originally suggested arrangement for purely practical reasons—it's easier to ask about (or modify, or migrate elsewhere) the entire history of a single project when there's a single repository path that holds the entire history—past, present, tagged, and branched—for that project and that project alone."

For my own, I tend to agree quite strongly with this and prefer the following layout: / utils/ calc/ trunk/ tags/ branches/ calendar/ trunk/ tags/ branches/ … office/ spreadsheet/ trunk/ tags/ branches/

The reason are simply that its impractical to tag a complete project set when one would want to tag only a specific subset.

Let's use an example: If project-1 depends on moduleA v1.1 and moduleB v2.3, I don't want newer moduleA v2.x to appear in the tags. In fact, when coming back some days/weeks/months later to this tagged release, I would be forced to open the bundle descriptor in the tagged version of project-1 to read the version of moduleA actually required.

Moreover, if I have to make a specific backup of this release's sources onto a CD, I just want to export this tag without downloading hundreds of megabytes of unrelated stuff.

It was just my two cents.

Answer 4

I've answered a similar question in a StackOverflow Version Control Structure question. It actually fits even better here since we do heavy OSGi development and have lots of bundles. I must echo Anders Sandvig comments: keep trunk/tags/branches on the root level since you will only branch a limited set of modules. It also does not interfere with modules building individually.

I won't copy the answer I made before but it is entirely relevant to this question.