Repository Organization
Always remember that top-level directories in the repository (i.e. those directly below /vesta) should be globally unique. To quote the repository server man page:
Warning: Every name created directly under /vesta (more precisely, directly under [UserInterface]AppendableRootName) must be globally unique across all repositories in the universe in the past, present, or future. If you break this rule, your repository will have problems participating in the replication protocol with those repositories that have conflicting names. We strongly recommend that every name you create in this directory be an Internet domain name that belongs to you; if everyone does so, uniqueness is guaranteed. Do not reuse a name unless you are certain that the previous use of the name has been permanently deleted in all repository replicas, including replicas that might be recreated from backup media or the like.
Below these globally unique top-level directories, Vesta allows you to create a hierarchy of directories to contain your packages. Vesta builds can use sources from multiple different packages, and most projects split up their sources into many different packages. Some important things to consider when creating a project hierarchy in Vesta:
Package contention: Normally when you run vcheckout, if someone else has the same package checked out you'll get an error message. There are a variety of ways around this (creating a branch with vbranch, performing a non-exclusive checkout with vcheckout -N). However, users often prefer to avoid these additional steps. Many projects try to minimize contention by the division of their sources into packages.
Planning for change: Over the course of a project, especially long-lived ones, you may have reason to change your Vesta repository hierarchy. However, because of Vesta's property of immortal names, you can't do things like rename existing packages. (See RepositoryRules and ReorganizingRepos.) The currently recommended practice is to number your top-level directories and expect to create additional ones as your project hierarchy changes.
Package mastership: Each package has a particular repository which holds its master copy. Peer repositories can check out remotely from it, and this can be essentially transparent to the user with the proper setup (see RemoteCheckoutSetup). However, it does require making network connections to the remote master repository, which can introduce additional delay and be problematic if there's a loss of connectivity or the master repository goes down. If you use multiple repositories, you may wish to place mastership of packages at those repositories which have some affinity to the individuals likely to be making changes to them. (See the vmaster(1) man page for how to explicitly move mastership between repositories.)
While there are no hard rules about naming, there are two second-level directory names (i.e. those below the Internet domain based names, such as "foo" in "/vesta/example.com/foo") which have a common usage in Vesta:
- platforms
This is normally used to store the packages containing OS component files (standard compilers and libraries, etc.). These are normally created with pkg2vesta and usually have a hierarchy below them that follows the convention "/vesta/example.com/platforms/os/vendor/cpu". See /vesta/vestasys.org/platforms for an example.
- bridges
This is normally used to store libraries of Vesta SDL code used for running different tools. See /vesta/vestasys.org/bridges for an example.
You might also want to look at the organization of sources under /vesta/vestasys.org to see how the Vesta project organizes its repository.