Synchronizing a Master CVS Repository
with a Local CVS Repository

Index

Overview

Audience

This document is aimed at two different communities of users: those that manage local Stargate repositories and those that manage a master Stargate repository (for example, on Sourceforge or on common institutional server).

Local Repositories

A Local Repository is a CVS repository that is set up on a user’s or institution’s local machine, that they typically have complete administrative control over. It is not necessary for you to have a local Stargate repository to contribute to the Stargate community. You may check out source from Sourceforge directly. However, creating a local repository provides several advantages: it is faster, gives you a place to make specific local customizations, and allows you to stage contributions before they are pushed to a master. It also introduces complexity: To remain current you will need to synchronize your local repository with a master. Part of this document describes how to do this and how to submit patches for consideration to the master.

Master Repositories

A Master Repository is a CVS repository from which master copies of the Stargate feed are obtained, typically on a remote or inaccessible machine. A master repository forms a parent/child relationship with a local repository. Local repositories can be masters to other repositories. This parent/child relation forms a tree of master and local repositories. For example, the platformx Sourceforge CVS repository is "the" master Stargate repository. There are local repositories in the UCLA CENS lab and Intel Research. In turn, the Intel Research repository is a master repository for a local repository used by an Intel researcher. This tree of repositories may be arbitrarily deep and wide. See the diagram below for an example. However, for many of us, it is sufficient to focus on the master on Sourceforge and a local repository.

By definition a master repository is under tighter control than local repositories because it serves a community of people, instead of just a single user. For example, the Sourceforge repository effects everybody, while a local institutional repository will affect only people at that organization. Typically a handful of people will manage each repository, their primary role is to evaluate patches and apply those appropriate for that repository. Another part of this document will describe how to do that. Furthermore, they are responsible for generating a patch to migrate their changes, if any, upstream to their master repository.

Sandboxes

A sandbox is a local working copy of a given repository. Files are changed in the sandbox, and then eventually committed to its associated repository. The sandbox may exist on the same machine as the repository, or on a different machine. When generating/applying a patch between two repositories, an intermediate sandbox is used to manage the changes.

 

Synchronization Phases

There a three phases is the synchronization process. See diagram below. Each is outlined in the remainder of this document. Not all phases need to be completed and different people are probably involved in each phase. Furthermore, it is not necessary for master and local repositories to be in sync. There may be things in our local repositories that we choose not to submit to a master.

Importing a Master Repository

This phase involves merging the master repository into a local repository. The term "merge" is significant. It does not make the repositories identical. In particular there may be local changes or enhances that have not be reflected into a master. This phase is done by people at a local site.

Generating a Patch for the Master Repository

This phase is also done by people at a local site. If it is determined that local changes would benefit the entire community, differences between the local and master repositories can be captured in a patch file and submitted for consideration by it administrators.

Updating Changes to a Master Repository

If the administrators of the master repository determine that a patch will be of general interest and the patch works, they may commit the changes to the master repository. Many such patches may be applied/committed to a repository. Eventually the repository will be tested and tagged with a new version number signifying a known or important milestone.

 

Importing a Master Repository

In this phase we will merge the master repository into a local one.

Assumed Initial State

It goes without saying that there are many ways sandboxes and local repositories can be organized. For the sake illustrations we will assume that the master repository in on Sourceforge and the local repository is on an Intel server named Silver.

For convenience we define a variable for each repository:
MCVS=:ext:edcepp@cvs.sourceforge.net:/cvsroot/platformx
LCVS=:pserver:silver.sc.intel.com:/consus

Operating in Steady State

If you are part of a team that shares a local repository, you can create a private sandbox (working directory). For example the following commands creates two sandboxes in our home directory.

cvs –d $MCVS co platx
mv platx platx-master

cvs –d $LCVS co platx
mv platx platx-local

Creating the Initial Version of Local Repository

If you are the first person to set up a local repository at your site, you will need to do the following after you do the initial CVS setup.

cvs –d $MCVS co platx
util/cvsimport –n –d $LCVS

The first line fetches a local version of the files, which is really only used to get access to the “cvsimport” script and a few configuration files. The second line does the actual work of importing all the relevant modules into the new local repository.

 

Merging the Master Repository into the Local Repository

This is the step the merges the enhancements in a master repository into a local repository. This process is summarized in the diagram below.

cd ~/platx-local
util/cvsimport
cd cvswork/merge

cvs update

cvs commit

This completes the merge of a master into a local repository.

 

Generating a Patch for the Master Repository

Making local changes

Edit your local repository (for example, in ~/platx-local) and commit any changes as necessary. This is an ongoing process of local enhancements. At some point local administrators may determine that their enhancements are of broad significances. So they decide to submit a patch to their master for all to benefit, or so that changes in a master repository do not conflict with further local changes.

Creating a patch

cd ~/platx-local
util/cvsrdiff

This generates a tar ball tamed platx.patch.tgz which contains all the files necessary to reflect changes to the master repository. The individual files used will also be left in platx.patch* files. You should check these files to make sure they have the appropriate information in them before submitting the patch. For example, you don't want to include editor back up files, intermediate files, or clutter that has been left around.

 

Updating Changes in a Master Repository

This step applies to those people who are responsible for the master repository. They assume that someone from the user community has generated a patch using the process above and requested that it be applied to the master.

Appling the patches

cd ~/platx-master
util/cvspatch -t platx.patch.tgz

The patch files will be left in cvswork/patch

cd ~/platx-master
util/cvspatch platx.patch.tgz

cvs commit

Updating the Tag in the Master Repository

Tag a master repository at some significant or stable milestone. Milestones may include major, minor, or pre releases and the inclusion of major new functionality.