Advanced PHP Programming

188 Chapter 7 Managing the Development Environment

> cvs -d /var/cvs co CVSROOT

Then in the file cvswrappers add a line like the following:

*.jpg -k ‘b’

Then commit your changes. Now any file that ends in .jpg will be treated as binary.

Modifying Files

You have imported all your files into CVS, and you have made some changes to them. The modifications seem to be working as you wanted, so you would like to save your changes with CVS, which is largely a manual system.When you alter files in your working directory, no automatic interaction with the master repository happens.When you are sure that you are comfortable with your changes, you can tell CVS to commit them to the master repository by using cvs commit. After you do that, your changes will be permanent inside the repository.

The following was the original version of examples/chapter-7/1.php:

<?php

echo “Hello $_GET[‘name’]”;

?>

You have changed it to take name from any request variable:

<?php

echo “Hello $_REQUEST[‘name’]”;

?>

To commit this change to CVS, you run the following:

> cvs commit -m “use any method, not just GET” examples/chapter-7/1.php Checking in examples/chapter-7/1.php; /var/cvs/Advanced_PHP/examples/chapter-7/1.php,v <-- 1.php

new revision: 1.2; previous revision: 1.1 done

Note the -m syntax, which specifies the commit message on the command line. Also note that you do not specify the CVS repository location.When you are in your working directory, CVS knows what repository your files came from.

If you are adding a new file or directory to a project, you need to take an additional step. Before you can commit the initial version, you need to add the file by using cvs add:

> cvs add 2.php

cvs add: scheduling file `2.php’ for addition

cvs add: use ‘cvs commit’ to add this file permanently

As this message indicates, adding the file only informs the repository that the file will be coming; you need to then commit the file in order to have the new file fully saved in CVS.

Examining Differences Between Files

A principal use of any change control software is to be able to find the differences between versions of files. CVS presents a number of options for how to do this.

At the simplest level, you can determine the differences between your working copy and the checked-out version by using this:

> cvs diff -u3 examples/chapter-7/1.php Index: examples/chapter-7/1.php

===================================================================

RCS file: /var/cvs/books/Advanced_PHP/examples/chapter-7/1.php,v

echo “Hello $_REQUEST[‘name’]”; +echo “\nHow are you?”;

?>

The -u3 option specifies a unified diff with three lines of context.The diff itself shows that the version you are comparing against is revision 1.2 (CVS assigns revision numbers automatically) and that a single line was added.

You can also create a diff against a specific revision or between two revisions.To see what the available revision numbers are, you can use cvs log on the file in question. This command shows all the commits for that file, with dates and commit log messages:

> cvs log examples/chapter-7/1.php

RCS file: /var/cvs/Advanced_PHP/examples/chapter-7/1.php,v

Working file: examples/chapter-7/1.php

----------------------------

=============================================================================

As you can see from this example, there are two revisions on file: 1.1 and 1.2.You can find the difference between 1.1 and 1.2 as follows:

> cvs diff -u3 -r 1.1 -r 1.2 examples/chapter-7/1.php Index: examples/chapter-7/1.php

===================================================================

RCS file: /var/cvs/books/Advanced_PHP/examples/chapter-7/1.php,v

-echo “Hello $_GET[‘name’]”; +echo “Hello $_REQUEST[‘name’]”; ?>

Or you can create a diff of your current working copy against 1.1 by using the following syntax:

> cvs diff -u3 -r 1.1 examples/chapter-7/1.php Index: examples/chapter-7/1.php

===================================================================

RCS file: /var/cvs/books/Advanced_PHP/examples/chapter-7/1.php,v

-echo “Hello $_GET[‘name’]”; +echo “Hello $_REQUEST[‘name’]”; +echo “\nHow are you?”;

?>

Another incredibly useful diff syntax allows you to create a diff against a date stamp or time period. I call this “the blame finder.” Oftentimes when an error is introduced into a Web site, you do not know exactly when it happened—only that the site definitely worked at a specific time.What you need to know in such a case is what changes had

been made since that time period because one of those must be the culprit. CVS has the capability to support this need exactly. For example, if you know that you are looking for a change made in the past 20 minutes, you can use this:

> cvs diff -u3 -D ‘20 minutes ago’ examples/chapter-7/1.php Index: examples/chapter-7/1.php

===================================================================

RCS file: /var/cvs/Advanced_PHP/examples/chapter-7/1.php,v

echo “Hello $_REQUEST[‘name’]”; +echo “\nHow are you?”;

?>

The CVS date parser is quite good, and you can specify both relative and absolute dates in a variety of formats.

CVS also allows you to make recursive diffs of directories, either by specifying the directory or by omitting the diff file, in which case the current directory is recursed.This is useful if you want to look at differences on a number of files simultaneously.

Note

Time-based CVS diffs are the most important troubleshooting tools I have. Whenever a bug is reported on a site I work on, my first two questions are “When are you sure it last worked?” and “When was it first reported broken?” By isolating these two dates, it is often possible to use CVS to immediately track the problem to a single commit.

Helping Multiple Developers Work on the Same Project

One of the major challenges related to allowing multiple people to actively modify the same file is merging their changes together so that one developer’s work does not clobber another’s. CVS provides the update functionality to allow this.You can use update in a couple different ways.The simplest is to try to guarantee that a file is up-to-date. If the version you have checked out is not the most recent in the repository, CVS will attempt to merge the differences. Here is the merge warning that is generated when you update 1.php::

> cvs update examples/chapter-7/1.php M examples/chapter-7/1.php

In this example, M indicates that the revision in your working directory is current but that there are local, uncommitted modifications.

192 Chapter 7 Managing the Development Environment

If someone else had been working on the file and committed a change since you started, the message would look like this:

> cvs update 1.php U 1.php

In this example, U indicates that a more recent version than your working copy exists and that CVS has successfully merged those changes into your copy and updated its revision number to be current.

CVS can sometimes make a mess, as well. If two developers are operating on exactly the same section of a file, you can get a conflict when CVS tries to merge them, as in this example:

> cvs update examples/chapter-7/1.php

RCS file: /var/cvs/Advanced_PHP/examples/chapter-7/1.php,v retrieving revision 1.2

retrieving revision 1.3

Merging differences between 1.2 and 1.3 into 1.php rcsmerge: warning: conflicts during merge

cvs update: conflicts found in examples/chapter-7/1.php C examples/chapter-7/1.php

You need to carefully look at the output of any CVS command. A C in the output of update indicates a conflict. In such a case, CVS tried to merge the files but was unsuccessful.This often leaves the local copy in an unstable state that needs to be manually rectified. After this type of update, the conflict causes the local file to look like this:

<?php

echo “Hello $_REQUEST[‘name’]”;

<<<<<<< 1.php

echo “\nHow are you?”;

=======

echo “Goodbye $_REQUEST[‘name’]”;

>>>>>>> 1.3 ?>

Because the local copy has a change to a line that was also committed elsewhere, CVS requires you to merge the files manually. It has also made a mess of your file, and the file won’t be syntactically valid until you fix the merge problems. If you want to recover the original copy you attempted to update, you can: CVS has saved it into the same directory as .#filename.revision.

To prevent messes like these, it is often advisable to first run your update as follows:

> cvs -nq update

-n instructs CVS to not actually make any changes.This way, CVS inspects to see what work it needs to do, but it does not actually alter any files.

Normally, CVS provides informational messages for every directory it checks. If you are looking to find the differences between a tree and the tip of a branch, these messages can often be annoying. -q instructs CVS to be quiet and not emit any informational messages.

Like commit, update also works recursively. If you want CVS to be able to add any newly added directories to a tree, you need to add the -d flag to update.When you suspect that a directory may have been added to your tree (or if you are paranoid, on every update), run your update as follows:

> cvs update -d

Symbolic Tags

Using symbolic tags is a way to assign a single version to multiple files in a repository. Symbolic tags are extremely useful for versioning.When you push a version of a project to your production servers, or when you release a library to other users, it is convenient to be able to associate to that version specific versions of every file that application implements. Consider, for example, the Text_Statistics package implemented in Chapter 6.That package is managed with CVS in PEAR.These are the current versions of its files:

> cvs status

cvs server: Examining .

===================================================================

Instead of having users simply use the latest version, it is much easier to version the package so that people know they are using a stable version. If you wanted to release version 1.1 of Text_Statistics, you would want a way of codifying that it consists of CVS revision 1.4 of Statistics.php and revision 1.3 of Word.php so that anyone could check out version 1.1 by name.Tagging allows you do exactly that.To tag the current

194 Chapter 7 Managing the Development Environment

versions of all files in your checkout with the symbolic tag RELEASE_1_1, you use the following command:

> cvs tag RELEASE_1_1

You can also tag specific files.You can then retrieve a file’s associated tag in one of two ways.To update your checked-out copy, you can update to the tag name exactly as you would to a specific revision number. For example, to return your checkout to version 1.0, you can run the following update:

> cvs update -r RELEASE_1_0

Be aware that, as with updating to specific revision numbers for files, updating to a symbolic tag associates a sticky tag to that checked-out file.

Sometimes you might not want your full repository, which includes all the CVS files for your project (for example, when you are preparing a release for distribution). CVS supports this behavior, with the export command. export creates a copy of all your files, minus any CVS metadata. Exporting is also ideal for preparing a copy for distribution to your production Web servers, where you do not want CVS metadata lying around for strangers to peruse.To export RELEASE_1_1, you can issue the following export command:

>cvs -d cvs.php.net:/repository export -r RELEASE_1_1 \ -d Text_Statistics-1.1 pear/Text/Statistics

This exports the tag RELEASE_1_1 of the CVS module pear/Text/Statistics (which is the location of Text_Statistics in PEAR) into the local directory

Text_Statistics-1.1.

Branches

CVS supports the concept of branching.When you branch a CVS tree, you effectively take a snapshot of the tree at a particular point in time. From that point, each branch can progress independently of the others.This is useful, for example, if you release versioned software.When you roll out version 1.0, you create a new branch for it.Then, if you need to perform any bug fixes for that version, you can perform them in that branch, without having to disincorporate any changes made in the development branch after version 1.0 was released.

Branches have names that identify them.To create a branch, you use the cvs tag -b syntax. Here is the command to create the PROD branch of your repository:

> cvs tag -b PROD

Note though that branches are very different from symbolic tags.Whereas a symbolic tag simply marks a point in time across files in the repository, a branch actually creates a new copy of the project that acts like a new repository. Files can be added, removed, modified, tagged, and committed in one branch of a project without affecting any of the

other branches. All CVS projects have a default branch called HEAD.This is the main trunk of the tree and cannot be removed.

Because a branch behaves like a complete repository, you will most often create a completely new working directory to hold it.To check out the PROD branch of the Advanced_PHP repository, you use the following command:

> cvs checkout -r PROD Advanced_PHP

To signify that this is a specific branch of the project, it is often common to rename the top-level directory to reflect the branch name, as follows:

> mv Advanced_PHP Advanced_PHP-PROD

Alternatively, if you already have a checked-out copy of a project and want to update it to a particular branch, you can use update -r, as you did with symbolic tags, as follows:

> cvs update -r Advanced_PHP

There are times when you want to merge two branches. For example, say PROD is your live production code and HEAD is your development tree.You have discovered a critical bug in both branches and for expediency you fix it in the PROD branch.You then need to merge this change back into the main tree.To do this, you can use the following command, which merges all the changes from the specified branch into your working copy:

> cvs update -j PROD

When you execute a merge, CVS looks back in the revision tree to find the closest common ancestor of your working copy and the tip of the specified branch. A diff between the tip of the specified branch and that ancestor is calculated and applied to your working copy. As with any update, if conflicts arise, you should resolve them before completing the change.

Maintaining Development and Production Environments

The CVS techniques developed so far should carry you through managing your own personal site, or anything where performing all development on the live site is acceptable.The problems with using a single tree for development and production should be pretty obvious:

nMultiple developers will trounce each other’s work.

nMultiple major projects cannot be worked on simultaneously unless they all launch at the same time.

nNo way to test changes means that your site will inevitably be broken often.

To address these issues you need to build a development environment that allows developers to operate independently and coalesce their changes cleanly and safely.

196 Chapter 7 Managing the Development Environment

In the ideal case, I suggest the following setup:

nPersonal development copies for every developer—so that they can work on projects in a completely clean room

nA unified development environment where changes can be merged and consolidated before they are made public

nA staging environment where supposedly production-ready code can be evaluated

nA production environment

Figure 7.1 shows one implementation of this setup, using two CVS branches, PROD for production-ready code and HEAD for development code. Although there are only two CVS branches in use, there are four tiers to this progression.

Figure 7.1 A production and staging environment that uses two CVS branches.

At one end, developers implementing new code work on their own private checkout of the HEAD branch. Changes are not committed into HEAD until they are stable enough not to break the functionality of the HEAD branch. By giving every developer his or her own Web server (which is best done on the developers’ local workstations), you allow them to test major functionality-breaking changes without jeopardizing anyone else’s work. In a code base where everything is highly self-contained, this is likely not much of a worry, but in larger environments where there is a web of dependencies between user libraries, the ability to make changes without affecting others is very beneficial.

When a developer is satisfied that his or her changes are complete, they are committed into the HEAD branch and evaluated on dev.example.com, which always runs HEAD.