How the Repository is Organized

The projects contained in the developer network source code repository are organized in a consistent fashion. This enables developers to find their way in any of the source code projects and for the website to automatically find and display data about the projects.

Our directory layout is organized according to the recommendations set down by the authors of Version Control with Subversion (2004, O'Reilly Media). These guys have been using Subversion as long as anyone.

Their recommendations for repository layout are best expressed in Figure 4-2 from the book, and reproduced here:

In a nutshell, each project (or codebase) has a directory at the top of the tree. Inside of each project are a trunk directory and 0 or more branch or tag directories. The reason for this is the way that Subversion handles branches and tags--they are just copies of the files in the repository. When you create a branch, you are creating a copy, as expressed in Figure 4-3 from the book, reproduced here:

Cheap Copies

"Wait a minute," you say, "isn't this wasteful?" Well, no. Subversion uses what we call rocket-science to make copies cheap. Here's an excerpt from the book that explains things:

Subversion's repository has a special design. When you copy a directory, you don't need to worry about the repository growing huge--Subversion doesn't actually duplicate any data. Instead, it creates a new directory entry that points to an existing tree. If you're a Unix user, this is the same concept as a hard-link. From there, the copy is said to be "lazy". That is, if you commit a change to one file within the copied directory, then only that file changes--the rest of the files continue to exist as links to the original files in the original directory.

So, you see, it all does make sense after a bit. Go read the book--the entire book from cover to cover. Buy it when it comes out. The lessons you'll learn from it will help you throughout your Subversion-using days.

Additional Mark Logic Developer Network Specific Information

In order to make the developer network run more smoothly, we've added a few things to the basic layout specified by the Subversion book authors. In order to be treated as a first class project in our repository, the layout of the project must conform to the following structure:

  • Project Directory
    • trunk/*
    • branches/*
    • project/project.xml
    • releases/*

The project/project.xml file contains basic information about the project including the project name and a short description. The releases folder contains the distribution files (.zip archives) that the project makes available to the public.

Read More

To learn more about how this all goes together--and more tips and tricks for using Subversion, read the rest of the book. Here are some links for you:

A Note About Credit

The information from the book Version Control with Subversion. is used with permission. The contents of the book are licensed under the Creative Commons Attribution 1.0 License. The original authors are Ben Collins-Sussman, Brian W. Fitzpatrick & C. Michael Pilato. And they rock.