 |
phoneME Repository Structure
This topic describes the structure of the phoneME subversion repository. The diagram below shows the significant pieces of the repository structure.
ROOT----+----builds
|
+----components----+----cdc-------+----branches
| | |
| | +----tags
| | |
| | +----trunk
| |
| +----cldc------+----branches
| | |
| | +----tags
| | |
| | +----trunk
| |
| +----jsr120----+----branches
| | |
| | +----tags
| | |
| | +----trunk
| |
| +----midp------+----branches
| | |
| | +----tags
| | |
| | +----trunk
| |
| +---- ...
|
+----legal
|
+----releases
|
+----trunk---------www
Repository Overview and Rationale
This is quite an unconventional structure for a Subversion repository. In typical usage, there is a trio of subdirectories branches, tags, and trunk. The trunk is where mainline development occurs. If there is a need to copy the source base, modify it, and merge it back, this activity occurs under the branches directory. And when a snapshot of the source base is taken, such as for a release, that goes under the tags directory.
The phoneME repository is unusual in that the branches-tags-trunk structures occur within subdirectories of the components subdirectory. Our preferred development approach is for components to be developed as independently as possible. This leads to a requirement for branching and tagging to occur at the level of each component instead of at the root of the hierachy. This structure discourages changes that affect more than one component simultaneously, since that style of development leads to increased inter-component coupling. For example, a developer working on the midp component might need to do some significant, independent development. She could do this by creating a branch of just the midp component. Her branch need not contain copies of all the other components. It would be very difficult for her to accidentally make some interdependent changes in another component. Similarly, when the cdc component reaches a significant point in its development, a tag would be created for it alone, not for the whole tree.
The alternative would be to have a conventional repository structure with the branches-tags-trunk trio at the root of the hierarchy. This would work, but it could be confusing. In the first example, the developer working on midp would have her branch contain all the components, not just midp. It wouldn't be clear that her branch was for the sole purpose of her work on midp. In the second example, a tag created for cdc would contain a snapshot of not just the cdc component, but also of all the other components. These components would be at some arbitrary and irrelevant point in their development, and this would obscure the reason for the existence of the tag: to be a snapshot of cdc.
Still another alternative would have been to have branches-tags-trunk at top level, but to have branches and tags contain copies of subtrees of the trunk instead of the entire trunk. Again, this would work, and it would solve the problems mentioned in the previous paragraph. However, it would also introduce additional confusion. Different subdirectories at the same level of the hierarchy would have different contents. This violates a common Subversion convention, where each branch and tag is a copy of the trunk. This could be alleviated through the use of a naming convention, e.g. tags for the cldc component would all be prefixed with "cldc". This could be done, but it seemed clearer to put a branches-tags-trunk structure with each component.
While we would like the components to be completely independent of each other, the actual situation is somewhat more complex. There are two projects being run within the phoneME repository, phoneME Advanced and phoneME Feature. They are in the same repository because they contain overlapping components. Specifically, phoneME Advanced contains cdc, jump, midp, and several of the JSRs, whereas phoneME Feature contains cldc, midp, and a different set of JSRs. The two projects are running in parallel, their releases are not synchronized, and the set of components within each project changes over time. There is no single hierarchy that can embody the relationships of the components to the different projects. We thus decided to have a "flat" collection of components. This is also the reason why mainline development occurs in the area named "components" instead of in separate areas named "phoneME Advanced" or "phoneME Feature".
Checking Out from the Repository
A consequence of this structure is that it is not possible to check out the right set of components with a single svn checkout command. If you were to check out the /components subtree, you would get every branch and every tag of every component, as well as the trunk of every component. This is probably 20 or 30 times too many files! Instead, you should check out the trunk (or the appropriate branch or tag) of each individual component, with a separate svn checkout command. For example, if you want to build cldc, pcsl, midp, and jsr120, you would issue the following commands:
svn co https://phoneme.dev.java.net/svn/phoneme/components/cldc/trunk cldc
svn co https://phoneme.dev.java.net/svn/phoneme/components/pcsl/trunk pcsl
svn co https://phoneme.dev.java.net/svn/phoneme/components/midp/trunk midp
svn co https://phoneme.dev.java.net/svn/phoneme/components/jsr120/trunk jsr120
This will get you the "latest and greatest" versions of each of these components. If you are concentrating on development of an individual component, you might want to check out the trunk of just this component and instead check out recent tags of the other components you are building with.
-- StuartMarks - 09 Feb 2007
|