Next: , Previous: Subprojects, Up: Top



11 Importing Project Versions

Prcs allows you to create a sequence of project versions out of a sequence of releases of a source directory tree. You may want to do this, for example, if you are installing successive versions of some system imported from elsewhere and wish to be able to retrieve old versions, while still saving space by storing only the changes between successive versions. (See package and unpackage, if you want to move or copy an entire project from one repository to another.)

Tracking imported versions

The process is simple. For concreteness, let us use the name P as the project name. For the first imported version, we create P and populate it with the first version of the imported source files. In the directory that contains the imported files, use the commands

     % prcs checkout P
     % prcs populate P
     # Edit P.prj #
     % prcs checkin P

The editing of P.prj might consist of setting the Project-Description and New-Version-Log attributes, and possibly adding :no-keywords options to some files.

When you receive a new release of P, place it in a directory structure and, at the top directory of that structure, use the commands

     % prcs checkout P P.prj
     % prcs populate -d P
     # Edit P.prj #
     % prcs checkin P

With the -d option, the prcs populate command will add any new files found in the working directory, but not listed in P.prj, and will remove any files listed in P.prj, but not present in the working directory. Again, you will probably want to edit the New-Version-Log attribute.

Imported software sources often have their own version designations, and you may want to have the prcs major version identifiers include all or part of these designations. Suppose the first such imported release is called 1.0-beta. In the working directory containing this release, you might type

     % prcs checkout -r1.0-beta.0 P
     % prcs populate P
     # Edit P.prj #
     % prcs checkin P

On receiving a new release from outside, say 1.1-beta, you would put it under a working directory and, from that directory, issue the commands

     % prcs checkout -r1.0-beta. P P.prj
     % prcs populate -d P
     # Edit P.prj #
     % prcs checkin -r1.1-beta. P

Keeping parallel local versions

Sometimes, you will have local modifications or enhancements to a piece of imported software, and want to bring your local version up to date with successive parallel releases of the imported software. To do this, use the procedure above for keeping the imported releases. Put your own local releases in another major version, let's say Local. To start with, you'll use the initial imported release:

     % prcs checkout -rV P P.prj
     # Edit the project #
     % prcs checkin -rLocal P.prj

Here, V is whatever prcs version number you have assigned to the vendor's (the imported) version. Continue making your local modifications in major revision Local. When a new external release comes in, first make sure the most recent version of your local version is checked in. Then put the new imported version into a fresh directory structure, populate a project file, and check it in as outlined above. For concreteness, let's say that your most recent local version is designated Local.5, and the newly-checked-in imported version is designated Vendor.3.

In the working directory for Vendor.3 (which you have just checked in), issue the command

     % prcs merge -rLocal.@ -n P

to see where the discrepancies are (or use prcs diff), and use

     % prcs merge -rLocal.@ P

to merge in the revisions since the last external release with the local changes since the last release. Edit the files to resolve conflicts, and edit P.prj as usual. Finally, check the result back in with

     % prcs checkin -rLocal P

which will create version Local.6. Its parent versions are Local.5 and Vendor.3. Alternatively, you could check out the local version, Local.5, and merge against the vendor branch

     % prcs merge -rVendor.@ P

and checkin as Local.6. The resulting parent versions are the same in either case, with the sense of all the merge operations reversed.

Handling renaming

Sometimes, you will find it desirable to rename the files you import and re-arrange their directory structure in your local version. You probably only want to perform this restructuring on the Local branch of the project, not the Vendor branch. Initially, you will create your first local version like this:

     % prcs checkout -rV P P.prj
     # Rename files #
     # Edit P.prj to change the names in the Files attribute so
     # as to correspond to your renaming.
     % prcs checkin -rLocal P.prj

Editing P.prj here consists simply in changing the file names, not the internal file identifiers. For example, if the file doc/mogrify.1 in branch V is to be called man/mogrify2.1 in the Local branch, you would rename the file:

     % mkdir man
     % mv doc/mogrify.1 man/mogrify2.1

and then you would edit the line for doc/mogrify.1 in P.prj, which might read

       (doc/mogrify.1 (P/0_foobar.1 1.1 644))

originally, into

       (man/mogrify2.1 (P/0_foobar.1 1.1 644))

The internal file identifier, therefore, records the correspondence between doc/mogrify.1 in the V branch and man/mogrify2.1 in the Local branch. When either of these files is updated and checked in, its new internal file identifier will be in the same internal-file family; thus the correspondence between the files is not lost.

The concept of an internal-file family (see Files attribute) was introduced to allow prcs diff and prcs merge to “do the right things” (that is, compare or merge against the appropriate files) even in the face of such restructuring. For example, when comparing a Local version to a Vendor version, prcs diff will compare doc/mogrify.1 from the Vendor version with man/mogrify.1 in the working files of your Local version.