Inhaltsverzeichnis von Practical Perforce

- Weitere Informationen zu diesem Buch:
  Inhaltsverzeichnis | Kolophon | Rezensionen |

JETZT ONLINE BESTELLEN

Practical Perforce

By Laura Wingerd

First Edition Dezember 2005
ISBN 978-0-596-10185-5

358 Seiten

EUR32.00

Weitere Informationen zu diesem Buch

Inhaltsverzeichnis | Kolophon | Rezensionen |

Inhaltsverzeichnis

Chapter 1: Files in the Depot

Inhaltsvorschau

This chapter describes how Perforce stores files and directories in its repository, the depot. It starts by introducing the syntax that allows you to work with depot files and follows with examples of how to browse the depot and get information. Finally, it touches on file properties and their effect on how Perforce handles file content internally.

You may be happiest using a GUI (graphical user interface) for your day-to-day work. This book, however, bases most of its examples on P4, the Perforce Command-Line Client. One reason we stick with P4 is simply that it's easier to create and write about text examples than it is to create and write about screenshots. So don't take our bias toward P4 as a snub of the Perforce GUI programs. In fact, we'll point out some P4V features that show you at a glance what P4 would take thousands of lines of output to tell you. On the other hand, the GUIs are somewhat limited—only P4 offers the complete lexicon of Perforce commands. So, while you are encouraged to use a GUI, expect to use the command line from time to time to do the things the GUIs don't do.

Perforce is widely used partly because it is so portable, and part of that portability comes from the platform-independent file syntax it provides. While native platform syntax can be used to refer to workspace files, Perforce provides its own uniform syntax for referring to workspace and depot contents. This syntax is known as a file specifier, or "filespec." A filespec can refer to a single file or a collection of files, to a specific revision or a range of revisions, and to depot files or workspace files. More importantly, the filespec syntax applies to all operating systems; Perforce converts filespecs to native file references for local operations.

Depots, where Perforce keeps master file content, and workspaces, where users work on files, are hierarchical structures of directories and files. A filespec uses "//" to indicate the root of the hierarchy, and "/" as a directory path and file name separator. For example:


//depot/projectA/doc/index.html

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

The Perforce Filespec Syntax

Inhaltsvorschau


//depot/projectA/doc/index.html

Although we often refer to an entire repository as "the depot", there can be multiple depots in a Perforce repository. The filespec root identifies the name of the depot. The filespec //depot/projectA/doc/index.html refers to a depot named "depot" (Figure 1-1.)

Figure 1-1: Filespecs and the depot hierarchy

A filespec can express a relative path as well as an absolute path. An unrooted filespec is a relative reference to the current directory (if you're using a command shell) or the current folder (if you're using a GUI). Depending on the context, doc/index.html or even just index.html could indicate the same file. In the chapter 2 section "Local Syntax, Wildcard Expansion, and Special Characters" you'll find out how to use relative references to files and directories.

When filespecs contain wildcards , they define entire collections of files instead of single files. For example, the "*" wildcard matches characters in filenames at a directory level. Depending on what files are actually present, a filespec like projectA/d*/*.html, for example, can define a collection of files like:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Browsing Depot Files

Inhaltsvorschau

You can do extensive browsing in a Perforce depot without having to set up a workspace of your own. In fact, there is very little reason to reproduce depot files locally just to see their contents. You can explore the depot hierarchy, peruse file history, read change descriptions, examine file content, and compare depot files, all without going to the trouble of setting up a workspace.

Many of the examples that follow are from the Perforce Public Depot. You, too, can browse the Public Depot by connecting to public.perforce.com:1666. (See Appendix A). However, some of the outputs shown here have been somewhat abridged to shorten line lengths and reduce clutter. If you connect to the Public Depot and try these commands for yourself, you'll get more verbose results.

The depot is a file tree, and the easiest way to navigate it is with a GUI. With P4V, for example, all you have to do is point and click to step down the tree and expand its subdirectories (or folders, as they're called in P4V). A P4V depot tree is shown in Figure 1-6.

Figure 1-6: Navigating the depot tree in P4V

However, you can also navigate from the command line, using P4. To list the topmost levels of the tree, for example, use this dirs command:


p4 dirs "//*"

//guest

//public

Notice that the dirs argument is quoted—that's so the command shell won't expand the asterisk before passing it to the p4 command.

Another way to show the top level of the depot hierarchy is with the depots command:


p4 depots

Depot guest  'Depot for guest users. '

Depot public 'Perforce's open source depot. '

The dirs command can be used at any level of the depot tree to list the subdirectories at that level. For example:


p4 dirs "//public/*"

//public/jam

//public/perforce

//public/revml

The changes command shows the history of a directory, listing the most recent changes first:


p4 changes -m5 //public/revml/...

Change 4971 on 2005/05/21 ... '- Added test to make sure big_r'

Change 4970 on 2005/05/21 ... '- Allow sdbm files to handle la'

Change 4969 on 2005/05/21 ... '- Added a special command line '

Change 4968 on 2005/05/21 ... '- Use module name instead of lo'

Change 4967 on 2005/05/21 ... '- Removed "-d", leaving only "-'

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

File Types at a Glance

Inhaltsvorschau

Perforce does most of the hard work for you when it comes to storing and managing file content. However, there are some aspects of file storage and behavior that you can control. These aspects are a factor of a file's type; in this section we'll take a brief look at the common file types and their properties. In the next chapter we'll see examples of how to set and change file types.

Perforce supports several types of file content, text and binary being the most common. A file's content type dictates how Perforce will handle it in future operations:

Text files: Text files are stored in the depot as deltas. That is, a revision of a file is not stored in its entirety; only the lines that have changed are stored. Consequently, umpteen revisions of a very large text file don't take much depot space if only a small part of the file changes at each revision. Delta storage is completely transparent to the user, of course—the server takes care of constructing a specific file revision from deltas when you synchronize your workspace.
As it transfers text files to and from workspaces, Perforce translates them so that their line-end delimeters match the local filesystem's format. If your workspace is on Unix, for example, Perforce makes sure lines in text files end with the LF character. If you workspace is on Windows, Perforce makes sure lines end with the CR/LF character pair.
Binary files: Binary files are stored in the depot their entirety. Each revision is stored as a compressed copy of the file. The Perforce client program gets the file revision you need and uncompresses it when you synchronize your workspace. Other than compression, no modification is made to binary files when they are transferred between workspace and server.
Perforce can compare and merge text files. It can't do that with binary files, beyond simply pointing out that the files are different and letting you choose one or the other. (If you have programs that can compare and merge binary files, however, Perforce can invoke them for you. In Chapter 3 we'll take a closer look at this.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 2: Working with Files

Inhaltsvorschau

In this chapter, we'll survey the Perforce commands you're most likely to use for basic software development. We'll discuss creating and managing a workspace, working on files , and finding out who did what when. If you're already using Perforce, this chapter will be a review. You can skim through it—maybe you'll find something here you didn't know about—or skip it now and come back to it later if you care to.

If you're new to Perforce, this chapter will introduce you to a variety of useful commands. What's more, this chapter will serve as a quick reference to many common tasks. There's more to each of the commands introduced here, of course. You'll find the complete inventory of commands and command options in the P4 Command Reference.

You may wish to experiment with these commands as you read along. See Appendix A if you don't already have Perforce installed.

Whether you're a Perforce user or not, you'll need at least a glancing familiarity with the basic commands described in this chapter so that you can make sense of them as they appear throughout the book.

In Perforce, working on files involves setting up and synchronizing a workspace, adding and working on files, resolving parallel changes (if necessary), and submitting changes to the depot:

Setting up a workspace: The first thing you do before you can work on files is define a client workspace for yourself. A client workspace specification, or client spec, tells Perforce where in your local filesystem you want your workspace to be rooted. It has a view that defines the areas of the depot you want access to, and maps them to directories beneath the workspace root. Once you've set up your workspace, you can work on files.
Adding new files: If you have files in your workspace already—files that you created or moved there yourself—you can add them to the depot. In Perforce, any change you make—adding files , for example—involves two Perforce operations. First you

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

An Overview

Inhaltsvorschau

In Perforce, working on files involves setting up and synchronizing a workspace, adding and working on files, resolving parallel changes (if necessary), and submitting changes to the depot:

Setting up a workspace: The first thing you do before you can work on files is define a client workspace for yourself. A client workspace specification, or client spec, tells Perforce where in your local filesystem you want your workspace to be rooted. It has a view that defines the areas of the depot you want access to, and maps them to directories beneath the workspace root. Once you've set up your workspace, you can work on files.
Adding new files: If you have files in your workspace already—files that you created or moved there yourself—you can add them to the depot. In Perforce, any change you make—adding files , for example—involves two Perforce operations. First you open your workspace files, indicating whether you want to add, change, or delete them. Then, after making changes locally, you submit files to the depot.
Don't confuse Perforce's idea of open with the idea of opening files in applications. In Perforce, an open file is a file you intend to change. Opening a file with Perforce does not launch an application. And an application—Word or Vim, for example—can open a workspace file whether or not Perforce considers it open.
Synchronizing your workspace: To work on files that are already in the depot, you must first synchronize your workspace (see Figure 2-1). This step gets local copies of the latest depot files. Your workspace is considered to be "in sync" when all the files in it match their depot counterparts.

Figure 2-1: Synchronizing a workspace
Working on files: By default, Perforce creates nonwritable files in your workspace. This is meant as a gentle reminder to you that these files are under its control. Although you're free to do what you want in your workspace, including changing file permissions, the preferred method is to let Perforce know what you're up to by opening files first. You open files with commands that indicate what you plan to do—

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Creating A Workspace

Inhaltsvorschau

A Perforce workspace has a physical part and a conceptual part. The physical part is the area on your local disk where Perforce will read and write files. The conceptual part of your workspace is the client object that represents it in the Perforce database. The client object has to exist before you can do any work on files. You create it by editing a client spec .

The Perforce database models many non-file objects, including workspaces, users, user groups, depots, and so forth. The interface to these non-file objects is what Perforce calls a spec form. Perforce gives you a spec form to edit when you run commands like:


p4 client

To command line users, the spec form will be simply a text file that looks something like this:


Client: testws

Owner:  bill

Root:   c:\workspace\test

View:

    //depot/proj/...   //testws/proj/...

    //depot/utils/...  //testws/utils/...

Fields in the form start in the left-hand column. (In this example, the fields are Client, Owner, Root, and View.) The value in each field follows the field name. Single-line values can be placed on the same line as the field name. Multi-line values start on the line following the field name; each line in the value is indented by tabs or spaces.

The Perforce GUI programs (P4V and the rest) give you an actual form to fill out, so you don't have to worry about field names and indentation.

There will be plenty of references to spec forms in this book. We'll use a format for them that looks like this:


Client             testws

Owner              ron

Root               c:\workspace\test

View               //depot/proj/...   //testws/proj/...

                   //depot/utils/...  //testws/utils/...

This format is not what you'll see either in the GUI programs or in your editor. It's the same information, however; it's simply formatted for easy reading.

In this book, we'll often preface the spec form by the P4 command that launches it in your editor. If you're using a GUI, look for the equivalent command in the application menus. (In P4V, for example, a command that lets you edit a workspace client spec is Connection → Edit Current Workspace.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Synchronizing a Workspace

Inhaltsvorschau

The next step after configuring a workspace and making it the current workspace is to synchronize it. When you synchronize your workspace. Perforce does two things. First, it copies files from the depot to your local disk. Second, it makes an internal record of the file revisions you have on disk.

If you want a preview of the files you need to synchronize, or if you're simply interested in seeing which depot files have been updated since the last time you synchronized, use the sync command with the -n option:


p4 sync -n

Use the sync command to synchronize your workspace:


p4 sync

Without arguments, the sync command synchronizes your entire workspace. It copies the latest versions of depot files to their corresponding locations on your local disk. (Assuming there are files in the depot, of course. If you're using a virgin Perforce installation there won't be anything to synchronize with yet.)

If you're synchronizing for the first time, be sure to preview the operation first! In other words, run the following command first:


p4 sync -n

A common mistake is to start synchronizing before realizing that your workspace view is too large. This is not an irreparable situation, of course, but you can save yourself some grief by making sure you know what's going to be synchronized before Perforce starts filling up your disk.

You can run sync as often as you like—it refreshes only the files that have changed. Perforce is smart enough not to recopy files that are already present in your workspace.

Normally, commands like sync operate on your entire workspace. But you can also synchronize your workspace in bits and pieces. Just supply a filespec to the sync command. For example, this command effectively synchronizes the //depot/dev/www directory:


p4 sync //depot/dev/www/...

Another useful way to limit the scope of synchronization is with wildcards that match to only certain files:


p4 sync "//.../*.png"

This command synchronizes only the *.png files, rather than the entire workspace. (The

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Local Syntax, Wildcard Expansion, and Special Characters

Inhaltsvorschau

Once you have files in your workspace, refering to them with Perforce filespec syntax may be a bit confusing. However, you can also use the syntax native to your local machine to refer to workspace files. If your workspace is on Windows, for example, you can refer to a file with local syntax like:


c:\ws\projectA\www\index.html

For its internal operations, Perforce translates that to a depot filespec like:


//depot/projectA/www/index.html

(The actual location of the file in the depot is determined by the workspace view.)

If your current directory is beneath your workspace root, you can also use relative filenames. For example, if you're in the workspace directory mapped to the depot's //depot/projectA/www directory, you can use a command like:


p4 have index.html

to refer to the //depot/projectA/www/index.html file.

You can mix and match local syntax with filespec syntax. Usually you do this when you want to use Perforce revisions or wildcards with local file names. For example:


p4 sync c:\ws\projectA\...@Rel2.4

This hybrid of local syntax and filespec is acceptible. In this example, it identifies the collection of depot files that are mapped to the c:\ws\projectA path. The sync command shown here will copy the depot file revisions labeled @Rel2.4 to the workspace.

As you saw earlier, spaces in filenames and pathnames have to be quoted when they are referenced in views. The same goes for commands. Anywhere you enter a filespec—on a command line, or in a spec form—a space in a file or pathname is likely to be misunderstood. To prevent this, put quotes around the filespec. For example:


p4 have "My Dog.jpg"

With quotes as shown, P4 assumes there is one file argument, as you intended. Without quotes, P4 assumes you mean two files, My and Dog.jpg.

When you use P4 commands in a command shell, by the way, you should be aware that the shell is likely to expand special characters it recognizes before passing your file arguments to the P4 program. When you type:


p4 sync *.html

for example, the command shell may actually be invoking:


p4 sync index.html contacts.html

Thus, Perforce never sees your wildcard character and never gets a chance to expand it to the depot files it matches. To slip Perforce wildcard characters past the command shell, use quotes. For example:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Working with Local Files

Inhaltsvorschau

When you synchronize your workspace with depot files, Perforce normally puts read-only files on your local disk. To make files writable, you have to open them. You also have to open files you plan to add to or delete from the depot.

Remember, in Perforce, an "open file" is a file you plan to submit to the depot. Don't confuse Perforce's meaning of "open" with the idea of opening files in an application.

The basic flow of work in Perforce is that you open files as you work, then submit all your opened files at once when you have completed a unit of work. In this section we'll concentrate on ways to open files. In the next section we'll look at various ways to submit them.

Use the edit command to open files for editing. For example:


p4 edit index.html locations.html

Opening files for editing makes them writable so you you can edit them or otherwise modify them locally. None of your local changes are visible to other users, of course, until you submit your files to the depot:


p4 submit

Files you haven't submitted yet can be listed with the opened command:


p4 opened

//depot/dev/www/index.html#1  - add default change (text)

//depot/dev/www/prices.html#1 - add default change (text)

Each line of opened output shows a file revision, the reason it was opened (add), the pending changelist it belongs to (default change), and the file's type (text).

You can check to see who's working on any files at any time with opened -a:


p4 opened -a contacts.html

//depot/dev/www/contacts.html#3 - edit by tina

Also, you'll notice that as you open files, Perforce informs you if anyone else is working on them as well:


p4 edit contacts.html

//depot/dev/www/contacts.html#3 - opened for edit

... - also opened by tina@tina-web-prep

Just because you've opened files for editing doesn't mean you've gotten around to changing them. To list the opened files you've really changed, use:


p4 diff -sa

If you want to see the actual text diffs, use diff with no flags:


p4 diff

Because the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Working with Pending Changelists and Submitting Files

Inhaltsvorschau

As you open files, they are associated with a pending changelist. Your local changes don't affect the depot until you submit your files. What you submit to the depot is not individual files, really, but the entire pending changelist.

Use the submit command to submit a changelist:


p4 submit

By default, submit operates on the default pending changelist. (You can have more than one changelist, as you'll see in a moment.) Like the client command, submit launches an editor so that you can fill out a form. The form comes prefilled with the list of files in the changelist. All you really have to fill out for submit is the Description field. For example:


p4 submit

 

Description        Added feature and price list pages for the new web site.

Files              //depot/dev/www/index.html#1 - add

                   //depot/dev/www/price.html#1 - add

Once you save and exit the editor, Perforce begins sending your new and changed files to the depot. Submitting files goes very quickly—about as quickly as the files can be transfered over the network to the server. When all content has reached the server, and assuming you ran into no problems with permissions or triggers, new file revisions are created in the depot and your changelist description is recorded permanently.

It often comes as a surprise to new users that all the files in their changelists are submitted, even the ones that haven't been changed. New revisions whose contents are the same as their unchanged predecessors are created in the depot. If this behavior strikes you as unacceptible, you can revert your unchanged files before submitting them with:


p4 revert -a

Note that even though a file's content is unchanged, revert -a won't revert a file if you've resolved it or done anything to change its type.

Changelists are meant, among other things, to document files changed together as a single unit of work. However, it's easy to end up with unrelated files in your default pending changelist. If that happens, consider splitting your files into changelists that can be submitted separately.

You can create additional changelists with the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Removing and Restoring Files

Inhaltsvorschau

Removing files can mean a number of things in Perforce. Let's look at removing files—and restoring them, when possible—in three different contexts.

In the first context, you're removing Perforce-managed files from your workspace. In this case, you don't want to affect the depot files in any way—you simply want your workspace to be rid of them. You could remove them yourself, of course, since you have control over them. But it you did that, Perforce would be unaware that they're no longer there. Your have list would be out of kilter. You can prevent that by using Perforce commands to remove files from your workspace.

In a GUI like P4V this is simply a matter of selecting files or folders and clicking File → Remove from Workspace. With P4, however, removing files from your workspace is a little less intuitive. You do it by synchronizing to the symbolic revision #none. For example:


p4 sync c:\ws\dev\www\...#none

This command removes files previously synchronized, but only if they are not open. The open files produce a warning—to remove them you must revert first, then synchronize to #none.

To restore previously removed files to your workspace, simply resynchronize:


p4 sync c:\ws\dev\www\...

The next meaning of removing files is to delete them from the depot while keeping a history of their prior revisions intact. This operation does affect depot files, of course, and because it's a depot change, it requires you to synchronize the files, open them to be deleted, then submit a changelist. For example:


p4 sync c:\ws\dev\wwww\...

p4 delete c:\ws\dev\www\...

p4 submit

...

Change 4933 submitted

Perforce creates new head revisions of deleted files when you submit them—deleted revisions. Deleted file revisions have special properties. When people synchronize deleted revisions, Perforce removes the files from their workspaces. Deleted revisions also behave differently in resolve and integration operations, as we'll see in subsequent chapters.

You can restore deleted files by synchronizing with nondeleted revisions and adding them again. For example, we just saw a set of files deleted in changelist 4933. To restore this set of files, use:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Useful Recipes

Inhaltsvorschau

There are a couple of Perforce command recipes you may find yourself using often. One is the recipe for reconciling your workspace after working offline. The other is the recipe for backing out changes.

Once you've synchronized your workspace, you can do your development work completely offline. You could, for example, synchronize a workspace on your laptop before leaving the office, then work offline while riding the train home.

But your offline changes can't be submitted unless the files they involve are opened in a pending changelist. Once your laptop is back online you'll have to reconcile your offline changes—the state of your local files, in other words—with your pending changelist.

Reconciling offline changes is simply a matter of opening files after the fact. The formula is:

Find the files that were changed and open them for editing:
```
p4 diff -se | p4 -x- edit
```
Find the files that were removed and open them for deleting:
```
p4 diff -sd | p4 -x- delete
```
Find the files that are new and open them for adding. Assuming that you're in the top-level directory of your workspace, the Windows command to find files and add them is:
```
dir /s/b/a-d | p4 -x- add -f
```
On Unix that's:
```
find . -type f | p4 -x- add -f
```
(These dir and find commands list all the files in your local workspace tree and pipe them to P4's add command. The files that are truly new are opened for adding; the rest generate warnings but are ignored by add.)

Having done this, you can either submit your pending changelist or continue working on your opened files.

A change that has been submitted to the depot can be backed out by submitting another change that reverses it. There's a simple recipe for backing out a change. Assuming C is the change number, the recipe is:

Synchronize with the pre-@C files.
Open C's deleted files for adding.
Open C's edited or integrated files for editing.
Synchronize with the latest files.
Open C's added or branched files for deleting.
Resolve files.
Submit changelist.

This sequence of steps assures that the new change restores added, deleted, and edited files to their pre-C content and type.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 3: Resolving and Merging Files

Inhaltsvorschau

The previous chapter blithely mentions that you may have to resolve and merge files before submitting them. Resolving instructs Perforce to take care of files that been changed in parallel; merging is one way to resolve files. Resolving files is usually easy, and the result is usually exactly want you want, whether you understand how it came about or not. However, there are times when you do need to know exactly how files are resolved and merged. That is what this chapter is about.

This chapter starts out with a review of the Perforce resolve operation:what it's for, when you do it, and what you do with it. It nails down the meanings of "yours" and "theirs," the often-puzzling names Perforce gives to files being resolved. Next, it describes how Perforce actually merges text files. It shows how a merged file is constructed, and explains where and why conflicts are detected. (Merge results that seemed random to you before you read this chapter will seem completely predictable to you once you have read it.) This chapter also explains how to reconcile files that can't be resolved because they've been added, deleted, renamed, or moved. It offers tips for developers to resolve, merge, and reconcile files. Finally, it closes with a bit of arcana, including information about configuring alternate merge tools.

You must resolve files when:

You have files opened for editing, and you synchronize them with newer revisions.
You have files opened for editing, and your attempt to submit them fails because you aren't synchronized with the head revisions.
You are integrating changes between branched files.

The first two cases will be the focus of this chapter. However, most of what you will read here applies to the third case as well, so consider it prerequisite reading for the next chapter, Chapter 4.

Merge, conflict, resolve, and integrate are words that exacerbate the ambiguities of SCM terminology. Before we go any further, let's get clear about what these words mean—at least, in the context of this chapter:

By merge, we mean merging the contents of one file into another. Much of this chapter dwells on how Perforce merges files. Don't confuse this with the concept of merging changes from one branch into another. Perforce can do this kind of merging, too, only Perforce calls it

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Resolving: When, What, and How

Inhaltsvorschau

You must resolve files when:

You have files opened for editing, and you synchronize them with newer revisions.
You have files opened for editing, and your attempt to submit them fails because you aren't synchronized with the head revisions.
You are integrating changes between branched files.

The first two cases will be the focus of this chapter. However, most of what you will read here applies to the third case as well, so consider it prerequisite reading for the next chapter, Chapter 4.

By merge, we mean merging the contents of one file into another. Much of this chapter dwells on how Perforce merges files. Don't confuse this with the concept of merging changes from one branch into another. Perforce can do this kind of merging, too, only Perforce calls it integrating. We'll cover integration in Chapter 4.
If you and I both change index.html, that's a parallel change. Some SCM systems use the word conflict when they mean parallel change. But in this chapter, conflict means a condition that can be detected when parallel changes are merged. For example, you changed <img src=logo.gif> to <img src=img/logo.gif>, and I changed it to <img src=newlogo.gif>—that's a conflict.
You have to tell Perforce what to do with parallel changes. That's called resolving files, and you use Perforce's resolve command to do it. Merging is one of the options you have when you resolve files; resolve can merge files for you. And, after merging, you may have to resolve conflicts . But the resolve command doesn't resolve conflicts. It alerts you to the presence of conflicts and launches an editor so that you can resolve conflicts by editing the merged file.

To lay the groundwork for resolving and merging, let's take another look at what it means to be in sync with the depot. When you synchronize, Perforce fetches files from the depot. For example:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

How Perforce Merges Text Files

Inhaltsvorschau

Any two files can be compared to reveal diffs. Three files are necessary to merge content, a starting version and two modified versions.

Three-way file merging is an operation you'll find in many content-management tools. Perforce itself implements a three-way merge that operates on lines of text , not on characters, words, or other context-specific syntax. Some three-way merge tools can operate on characters, words, paragraphs, XML structures, HTML markup, programming language syntax, and so forth. If line-by-line merging isn't suitable for the kinds of files you're working with, you can configure Perforce to use another merge tool when resolving files. See "Configuring an alternate merge tool."

In Perforce's three-way merge, the "base" is the starting version and "yours" and "theirs" are the two modified versions of the file. Yours and theirs are each compared to the base so that lines in the three files can be grouped into "chunks ." Each chunk in the base is determined to be changed or unchanged with respect to yours and theirs. Chunks that are added or deleted are considered changed. Perforce constructs a merged file from the chunks using these rules:

When a chunk is the same in all three files, it goes into the merged file.
When a chunk has been changed in either yours or theirs, but not in both, the changed chunk goes into the merged file.
When a chunk has been changed in both yours and theirs, and the change is identical, the changed chunk goes into the merged file.
When a chunk is different in all three files, a conflict marker is placed at that location in the merged file. It will be up to you to decide what goes there.

Figure 3-8 shows a simple file merge. When the base file is compared to yours and theirs, six chunks are detected. The merged file consists of:

Chunks 1, 3, and 5 from the base. These are chunks of text neither you nor they changed.
Chunk 2 from yours. (Or theirs—both of you made the identical change.)
Chunk 4 from theirs. You made no change in that spot, but they did, so their chunk goes into the merged file.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Reconciling Structural Changes

Inhaltsvorschau

Parallel changes that affect depot structure can't be resolved in the same way as can parallel changes to file content alone. Among the changes that can't be resolved are changes where files have been added, deleted, renamed, moved, or combined. Perforce won't schedule files for resolving when:

You have files opened for editing and you synchronize with newer depot revisions that are deleted. (In other words, someone else has deleted files you are working on.)
You have files opened for deleting and you synchronize with newer, edited depot revisions. (In other words, someone else has edited the files you are about to delete.)
You have files opened for adding or branching, and you synchronize with non-deleted depot revisions of files with the same names. (In other words, someone else has already added or branched files before you.)

Perforce does warn people who are opening files if other users have the same files opened. And people should heed these warnings, especially if they're opening files for refactoring or other structural changes. But sometimes they just don't realize that structural changes can't be resolved, and sometimes they have reasons to submit their changes anyway. All is not lost—there are ways to reconcile structural changes.

The advice that follows works best if you make a habit of synchronizing, resolving, and reconciling changes incrementally, as described in "Tips for Smoother Collaboration" later in the chapter.

Let's start with a simple case: You opened some files for adding, and in the meantime, someone else has added files with the same names to the depot. You have resynchronized, but that doesn't affect these files in your workspace. You still have them opened for adding, and you won't be able to submit them.

To detect files in this state, look for files that are both opened for adding and already in the depot:


p4 opened diag04.gif

//depot/dev/www/img/diag04.gif#1 - add default change

 

p4 files diag04.gif

//depot/dev/www/img/diag04.gif#1 - add change 4761

Here, for example, you were going to add

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Tips for Smoother Collaboration

Inhaltsvorschau

An SCM tool can do only so much to make collaborative development possible. The rest is up to developers. Here are some things developers can do to keep collaboration going smoothly.

When you're working on files in parallel with other developers, resynchronize your workspace regularly. The longer you put off resynchronizing, the harder it is to get caught up. And if you're not caught up, you can't submit files.

Also, instead of resynchronizing individual files, resynchronize all the files in the scope of your work. (The scope could be a directory, several directories, or even your entire workspace.) This keeps your files in sync with each other and assures that when you try to compile or test, you'll have a set of files known to work together.

When you're working in a heavily concurrent environment, it's easier to resolve or otherwise reconcile changes before you attempt to submit files than it is after a submit command fails. So, before you submit, check to make sure you're synchronized:


p4 sync -n

If you're not, synchronize and resolve one changelist at a time, as described in the next section, then submit your files.

If resynchronizing regularly is going to make it difficult for you to do your work, consider working in a private branch. See Chapter 10.

We tend to speak of synchronizing as a way to get caught up with the current state of the depot. But in fast-moving, parallel development projects, many changes can occur in a short time. Simply synchronizing to the latest revisions puts you in a position of having to resolve many peoples' changes at once. This can be confusing, if not downright hellish.

If smooth collaboration is your goal, synchronize, resolve, and reconcile one changelist at a time. Here's a recipe for changelist-by-changelist synchronization. Run these commands from the root of the file tree that encompasses the scope of your work:

First, determine the changelist you're currently synchronized with:


p4 changes -m1 ...#have

Change 9284 on 2004/03/01 by jim 'Swap project names'

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

The Arcana of Merging

Inhaltsvorschau

What you've read so far may be all you need to know about resolving and merging files for your day-to-day work. In this section we'll take a look at a few advanced and arcane topics that may prove useful in special situations.

Earlier you read that when you auto-resolve files with merging, Peforce skips files if it finds parallel changes that conflict. There is a way to force Perforce to auto-resolve all files with merging even when there are conflicts. Use:


p4 resolve -af

The -af flag makes resolve work the same way as -am, but instead of skipping files with conflicts, it goes ahead and merges changes, leaving conflict markers in the resulting files. Forcing a merge of the files in "A simple file merge," earlier in this chapter, for example, writes this result to your workspace file, as:


cats

dogs

pigs

horses

sheep

cows

>>>> ORIGINAL

aunts

=  ==  = THEIRS

=  ==  = YOURS

ants

<<<<

The advantage of forcing merges is that you can resolve everything at once and edit the conflicts later. But this small advantage may be outweighed by several disadvantages:

Forced merging overwrites your workspace files with files that are never syntactically correct. Until you edit them, they won't compile or behave properly in any way.
Once you've resolved a file by forcing a merge, the file is ready to submit, as far as Perforce is concerned. There's nothing in Peforce that warns you that you've left conflict markers in files you are submitting.
If you forget to edit the conflict markers in a file before resynchronizing and merging newer changes to it, the conflict markers will themselves be treated as file content. And if these lines conflict with the newer changes, the result will be very, very confusing.

You can't undo a resolve. Once you've resolved a file, it's resolved:


p4 resolve -am index.html

c:\ws\doc\index.html

- merging //depot/projectA/doc/index.html#17,#18

merging from //depot/projectA/doc/index.html

 

p4 resolve -am index.html

No file(s) to resolve.

Even if you synchronize a resolved file to a newer revision, it stays resolved with respect to previously resolved revisions.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 4: Branching and Integration

Inhaltsvorschau

In the course of software development, we branch files to do concurrent, parallel work on them, and we integrate files to combine the results of such work. In this chapter, we'll look at how to do branching and integration with Perforce.

This chapter won't dwell on reasons to branch, what to branch, or how to work with different kinds of branches, Not that those things aren't important—they are, and they'll be given due consideration in Part II. But for now, we'll limit our discussion to the mechanics of branching and integrating.

In this book we use the term branch to mean a set of files that is a variant of another, each set evolving independently. (Codeline and stream are other words for this set.)

Don't confuse the term branch with the P4 branch command. The command creates Perforce database objects called "branches" but these objects are not branches at all. They're really branch views . We'll discuss branch views later in this chapter.

It's common to hear people in the software development world say they merge changes from one branch into another. In Perforce, we say we integrate changes from one branch into another. This is not a capricious choice of words. It's based on the notion that, even when two branches are closely related, not all changes in one branch can be merged into the other. Even so, every change has to be accounted for when you're trying to figure out what needs merging. (Why was this change never merged? Is it not applicable? Or did someone simply forget to merge it? )

The business of accounting for every change is what Perforce calls integrating. A change can be integrated from branch to branch by merging, when appropriate, or by simply deciding that it should be ignored. In either case, the change is considered integrated when you've decided what to do about it and Perforce has recorded your decision.

Of all the uses for branching , the one best understood is that of branching recently developed software for a product release. For example, assume that we are Ace Engineering and that we've been working on a software product called Ace. We're gearing up to make the first release of Ace available. Our plan is to release Ace Version 1.0 while simultaneously developing new features for a future release. For this, we're going to have to make a branch.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

The Classic Case for A Branch

Inhaltsvorschau

So far, there's one tree of files that constitutes the Ace product. It's in the //Ace/MAIN directory path of our depot. Until now, we've all worked together on the files in the //Ace/MAIN tree, shown in Figure 4-1.

Figure 4-1: One tree of files

With Perforce, we can simply clone the //Ace/MAIN file tree into a new //Ace/V1 file tree. This allows us to continue working on new features in the //Ace/MAIN tree. Meanwhile, those of us testing and stabilizing the 1.0 release can work in the //Ace/V1 tree. The two file trees are shown in Figure 4-2.

Figure 4-2: Cloning //Ace/V1 from //Ace/MAIN

At the outset, every file in the //Ace/MAIN tree has an identical counterpart in the //Ace/V1 tree. Over time, content diverges between the two trees as new development proceeds. The //Ace/V1 tree holds the stable, 1.0 version of the product, and the //Ace/MAIN tree holds the bleeding-edge, unreleased version.

This notion of cloning a tree of files from another is the essence of branching in Perforce. We clone a tree of files so that we can make changes to either tree—or branch—without affecting the other. The two file trees are peers in the depot hierarchy. Moreover, every file is a full-fledged file in its own right. Files in either branch can be edited, added, deleted, renamed, or moved. And changes made in one branch can be merged or otherwise integrated to the other.

Behind the scenes, Perforce keeps track of branching. Although every branched file is a file in its own right, its lineage is stored in the Perforce database. Perforce keeps track of a file's integration history as well. As we successively integrate changes between a pair of branches, Perforce uses file history to keep us from having to re-merge changes we've already merged.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Creating Branches

Inhaltsvorschau

As with all operations that affect depot files, creating a branch is a two-step process in Perforce. First you use integrate to open files for branching , then you use submit to make them appear in the depot.

So, back to our Ace example. We can think of the evolution of //Ace/MAIN as a single timeline, punctuated by submitted changelists. (see Figure 4-3.)

Now it's time to branch //Ace/MAIN into //Ace/V1. (We'll call these branches MAIN and V1, for short. See Figure 4-4.)

Figure 4-3: The evolution of //Ace/MAIN

Figure 4-4: Branching V1 from MAIN

Making the branch is simply a matter of using integrate to clone one directory from another:


p4 integ //Ace/MAIN/... //Ace/V1/...

//Ace/V1/db/Jamfile#1 - branch/sync from //Ace/MAIN/db/Jamfile#1,#32

//Ace/V1/db/dbAcc.cpp#1 - branch/sync from //Ace/MAIN/db/dbAcc.cpp#1,#3

//Ace/V1/db/dbDefN.cpp#1 - branch/sync from //Ace/MAIN/db/dbDefN.cpp#1,#7

...

(What's integ? An alias of integrate.) The integrate command takes two filespecs as arguments. The first identifies the donor files and the second identifies like-named target files—the files that will be created, in this case.

Whether it's used to branch, rename, or integrate files, the higher calling of integrate is to propagate change. Change comes from "donor files" and flows to "target files." Thus the integrate command always involves a pair of filespecs, one being the donor and the other the target.

As you can see, every file in MAIN is branched to a corresponding file in V1. For example, donor file //Ace/MAIN/db/Jamfile#32 is branched to target //Ace/V1/db/Jamfile#1. From integrate's output, we can infer that #32 is the head revision of the donor. The message branch/sync ... Jamfile#1,#32 lets us know that revisions #1 through #32 of the donor are going on record as having been integrated into revision #1 of the target.

Perforce bootstraps the new branch by copying donor files from the depot into target files in your workspace. (That's what the branch/sync messages in the output of

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Integrating Changes from Branch to Branch

Inhaltsvorschau

So, Ace Engineering now has two branches, V1 and MAIN. New development continues in MAIN as bugs are fixed and last-minute changes are submitted in V1. When and why to integrate are topics we'll discuss later in the book. For now, we'll focus on how it's done. In this case, let's assume we're interested in integrating V1's changes into MAIN.

The changes command tells us how the V1 branch has evolved:


p4 changes //Ace/V1/...

Change 3470 on 2004/10/05 by rob 'New threshold for...'

Change 3459 on 2004/10/05 by pete 'Fix titles of...'

Change 3456 on 2004/10/04 by rob 'Delete junk files...'

Change 3372 on 2004/10/04 by bill 'Branch V1...'

Not all of these changes need integrating to MAIN. Changelist 3372, as you recall, was the change that created the branch. To find out which changes do need integrating, we can use interchanges:


p4 interchanges //Ace/V1/... //Ace/MAIN/...

Change 3456 on 2004/10/04 by rob 'Delete junk files...'

Change 3459 on 2004/10/05 by pete 'Fix titles of...'

Change 3470 on 2004/10/05 by rob 'New threshold for...'

Whereas changes shows all changes to a branch, interchanges shows only the changes that are not accounted for in a target branch. (See "What interchanges really tells us" later in the chapter.) In this example we see that of the three changes made to V1 since it was created, none have been integrated to MAIN. Figure 4-11 shows these changes.

Figure 4-11: V1 changes not yet accounted for in MAIN

A very practical way to integrate changes between branches is incrementally—changelist by changelist, in order. This method preserves logical changes as they're propagated from branch to branch. It also keeps the problems of reconciling, resolving, and merging files to a minimum. It's a good technique to start off with, if you're not sure how to go about integating changes between branches.

Incremental integration is similar to branching from a point in time, using a changelist number instead of a date. Each time we integrate, we use interchanges to find out which changelist number to use.

Returning to the scenario in the previous example, here are the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Reconciling Structural Changes

Inhaltsvorschau

Earlier we said that files can evolve independently in their own branches. This is completely true. Files can be added, deleted, moved, renamed, split, or combined in one branch without affecting any other branch. However, structural changes like these can't be resolved during integration. In fact, when you use the integrate command, Perforce simply matches donor and target files by name. The state of each donor file, whatever it is, is imposed upon the like-named target file. If the donor file was deleted, integrate deletes the target file. If the target file doesn't exist, it branches the donor file into it.

Matching donor and target files by name is normally quite effective for propagating structural changes. For example, say MAIN/readme#8 was branched into V1/readme#1 when you created the V1 branch . Since then, the V1/readme file has been renamed to V1/readme.txt and edited a couple of times.

Now, as you integrate from V1 to MAIN, here's what happens:


p4 integ //Ace/V1/... //Ace/MAIN/...

//Ace/MAIN/readme.txt#1 - branch/sync from //Ace/V1/readme.txt#3

//Ace/MAIN/readme#11 - delete from //Ace/V1/readme#3

So far, so good. Although Perforce gave you no choice in the matter, and nothing is left for you to resolve, the outcome is exactly what you wanted. When you submit your changelist, Perforce will delete MAIN/readme and branch V1/readme.txt into MAIN, effectively propagating both the content change and the structural change from V1 to MAIN.

But what if you wanted to merge the content change and ignore the structural change? What if the structural change had occured in MAIN instead of V1? Neither integrate nor resolve offers a way for you to handle these cases. However, as with files you're editing, there are several ways to reconcile structural changes. One way is to provide Perforce with some guidance as to how branches correspond structurally. This is where branch views come in.

To save you from having to jot down your frequently used donor and target filespecs on a cocktail napkin, Perforce lets you save them in named, reusable

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

The Arcana of Integration

Inhaltsvorschau

(Heavens, it's all rather arcane, isn't it?)

It's worth noting that there are ways to reconcile branches so that changes can be integrated between them even when files have been split or combined in one of them. Reconciling split and combined files is a bit of a parlor trick, but that it can be done at all is a distinguishing feature of Perforce.

Consider this case: after V1 was branched from MAIN, MAIN's parse.cpp was split into two files, parse.cpp and eval.cpp. Meanwhile, change 3472 has been submitted in V1 which affects parse.cpp.

As is your custom, you integrate change 3472 from V1 to MAIN thus:


p4 integ -b V1toMAIN @3472

...

//Ace/MAIN/parse.cpp#5 - integrate from //Ace/V1/parse.cpp#2

...

MAIN's parse.cpp is opened for integrating, which is good. Maybe the change in V1's parse.cpp should be merged into it. But what if the change should be merged into MAIN's eval.cpp? What if part of the V1 change should be merged into MAIN's parse.cpp and part of it should be merged into eval.cpp?

Unfortunately, since nothing maps V1's parse.cpp to MAIN's eval.cpp, integrate has no way of knowing it should open the latter. Even if there were such a mapping in the V1toMAIN branch view, it would eclipse the mapping between the two parse.cpp files, because there can be only one mapping per file in a branch view. (When there is more than one, the last takes precedence.)

However, there's nothing to keep you from running more than one integrate command. If you know that part of MAIN's parse.cpp has been spun off into eval.cpp, you can integrate change 3472 using a pair of integrate commands:


p4 integ -o -b V1toMAIN @3472

...

//Ace/MAIN/parse.cpp#6 - integrate from //Ace/V1/parse.cpp#2

  using base //Ace/V1/parse.cpp#1

...

 

p4 integ -o //Ace/V1/parse.cpp@3472 //Ace/MAIN/eval.cpp

//Ace/MAIN/eval.cpp#1 - integrate from //Ace/V1/parse.cpp#2

  using base //Ace/MAIN/parse.cpp#5

This sequence of commands opens two target files for integrating from the same donor file. When you resolve them—which you should do interactively—you'll have a chance to pick the correct merged result for each. Whether it's easy or hard to pick a merged result, and whether conflicts are involved, will depend on how the MAIN file was split and how the V1 file was changed.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 5: Labels and Jobs

Inhaltsvorschau

Software configuration management is not complete without a way to save snapshots of file configurations so we can restore them later. Nor is it complete without a way to link external issues like bug reports, change requests, and to-do lists to the work we do on files. In this chapter, we'll look at how to do these things in Perforce, including using labels and jobs.

There are a number of ways to mark and restore file configurations in Perforce:

You can use changelist numbers. Every changelist number is a snapshot of the depot.
You can use dates and timestamps. Perforce knows the state of the depot at any point in time.
You can use labels. Labels can be applied to depot snapshots and to workspace-synchronized revisions as well as to arbitrary collections of files at mix-and-match revisions. And because labels can have descriptive names, they are easier to recognize than changelist numbers.
You can use jobs. Jobs can be linked to changelist numbers, giving you a way to mark the depot snapshots that are important to you. Like labels, jobs can have descriptive names.

Each of these methods has its pros and cons, as you'll learn from reading this chapter.

Every time a user submits files to Perforce, a snapshot of the depot is created automatically. The changelist number created at submit time is effectively a global revision number. It can be use to reference any file or set of files in the depot snapshot.

For instance, Ann submits a changelist:


p4 submit

Locking 2 files ...

edit //depot/www/index.html#9

add //depot/www/products.html#2

Change 5624 submitted.

As you can see, Ann's changelist contained only two files. However, by submitting it, she has created the revision identifier @5624.

This identifier can be used with any filespec to refer to the depot snapshot created when Ann submitted her files. Weeks later, for example, Roy might want to use it to synchronize his workspace with a snapshot of //depot/appserver as of that moment:


p4 sync //depot/appserver/...@5624

Dates or dates with a timestamp can also be used as snapshot revisions. Perforce supports two date formats:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Saving Important Configurations

Inhaltsvorschau

There are a number of ways to mark and restore file configurations in Perforce:

You can use changelist numbers. Every changelist number is a snapshot of the depot.
You can use dates and timestamps. Perforce knows the state of the depot at any point in time.
You can use labels. Labels can be applied to depot snapshots and to workspace-synchronized revisions as well as to arbitrary collections of files at mix-and-match revisions. And because labels can have descriptive names, they are easier to recognize than changelist numbers.
You can use jobs. Jobs can be linked to changelist numbers, giving you a way to mark the depot snapshots that are important to you. Like labels, jobs can have descriptive names.

Each of these methods has its pros and cons, as you'll learn from reading this chapter.

For instance, Ann submits a changelist:


p4 submit

Locking 2 files ...

edit //depot/www/index.html#9

add //depot/www/products.html#2

Change 5624 submitted.

As you can see, Ann's changelist contained only two files. However, by submitting it, she has created the revision identifier @5624.


p4 sync //depot/appserver/...@5624

Dates or dates with a timestamp can also be used as snapshot revisions. Perforce supports two date formats:

YYYY/MM/DD
YYYY/MM/DD:HH:MM:SS

For example, to synchronize your workspace with a snapshot of the //depot/ourproject files as of October 12, 2004, you'd use:


p4 sync //depot/ourproject/...@2004/10/12

If you don't specify a time, Perforce assumes you mean the beginning of the 24-hour day. If what you really want is a snapshot that includes work done by the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Using Labels

Inhaltsvorschau

In Perforce, as in many SCM systems, you can tag files with a label. A label lets you use memorable names like REL2.0.1 or Best_JPEGs_for_t-shirts to refer to specific configurations of file revisions.

Use tag to appy a label to files. For example, to tag all the files in the //Ace/Products/R2.0/ path with the label Rel2.0.1_Beta1 you would use:


p4 tag -l Rel2.0.1_Beta1 //Ace/Products/R2.0/...

In P4V this is simply a matter of selecting a folder or a file, then picking the Label command from its context menu.

Normally, tag applies a label to the head revisions—that is, the newest revisions—of files. You can tag older revisions by supplying a revision to the file argument. For example, this tags the revisions that were newest as of 6:00 a.m. on February 1, 2004:


p4 tag -l Rel2.0.1_Beta1 //Ace/Products/R2.0/...@2004/02/01:06:00:00

A label can't have an all-numeric name, and it can't be the same as an existing workspace name. To list the labels already in existence, use:


p4 labels

Once a label has been applied, it can be used as shorthand to refer to an entire collection of files. For example, to synchronize a workspace with the files labeled Rel2.0.1_Beta1 you would use:


p4 sync @Rel2.0.1_Beta1

Note the @ character—that's not part of the label name; it's the syntax that tells Perforce you're using the label as a symbolic revision.

You read about symbolic revisons in Chapter 1. A label is a symbolic revision identifier just like a date or a changelist number and it can be used with filespecs in the same way. For example, let's assume the Rel2.0.1_Beta1 label has been applied to these files:


//Ace/Products/R2.0/app/db/fileA.cpp#3

//Ace/Products/R2.0/app/db/fileB.cpp#4

//Ace/Products/R2.0/app/ui/fileC.cpp#2

Any of these files can now be referred to with the symbolic revision @Rel2.0.1_Beta1. For example:


//Ace/Products/R2.0/app/db/fileA.cpp@Rel2.0.1_Beta1

refers to:


//Ace/Products/R2.0/app/db/fileA.cpp#3

Wildcards can be combined with labels. For example:


//Ace/Products/R2.0/app/db/*@Rel2.0.1_Beta1

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Using Jobs

Inhaltsvorschau

A job is an object in the Perforce database that can be used to tie development activity to external information. Jobs can be used for anything—requirements, project plans, to-do lists, milestones—but their most common use is for defect tracking.

As you read this section, you may begin to wonder if the commands that operate on jobs are too cumbersome and inconvenient for developers to use. The real power of jobs comes not from their convenience to users, but from their ability to provide a smart, persistent, Perforce-side data store for external defect-tracking systems. A number of open source and commercially available defect-tracking software systems work with Perforce jobs. (For more on this, go to the Perforce web site and navigate from Product Info to Defect Tracking.)

In this section we'll take a look at the underlying Perforce commands that support external defect tracking systems. Why? For one thing, you can use these commands to automate your SCM procedures. For another, they're the key to being able to detect bug fixes as they migrate from codeline to codeline, as you'll find out in Chapter 8.

A job is simply an instance of a data structure that consists of name-value pairs. Job data is stored in the Perforce database. Jobs may mirror external data, but no external database is actually required to support Perforce's job storage.

Here is an example of a job:


Job                job000321

Type               bug

Status             open

User               miriam

Date               2005/02/10

Description        Login dialog is wrong size.

Product            AcePack 3.0.1

Category           GUI

The fields in a job are determined by a site-wide template. A Perforce superuser can use the jobspec command to customize the template:


p4 jobspec

jobspec opens a specification form in which you can define fields and default values. We won't go into the details of customizing the job template, but here are the salient points:

Various data types (selection lists, multiple lines, and so forth) can be configured in the template, as can field names, default values, allowable values, and required fields.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Jobs as Changelist Markers

Inhaltsvorschau

You read earlier in the chapter that changelist numbers are more efficient than labels for accumulating large configurations. But changelists numbers have a drawback—there's nothing in their identifiers that makes them easy to recognize. When a thousand new changelists have accrued in the last week, how can you tell which ones are the nightly build snapshots? You could record important changelist numbers on a cocktail napkin, but you don't have to. You can mark them with jobs.

To use a job to mark changelist numbers, first create the job. You can give a job any name as long as it's unique (and as long as it doesn't contain spaces or the characters #, %, *, and @). If you don't supply a job name, Perforce will come up with one for you. For example, to create a job called NightlyBuilds, use:


p4 job NightlyBuilds

 

Job               NightlyBuilds

Description       Nightly builds of //depot/project/...

Once you've created the job, you can use the fix command to mark a changelist with it. Here we use the NightlyBuilds job to mark changelist 1245:


p4 fix -c1245 NightlyBuilds

You can't use a job name to refer directly to files because, unlike labels, jobs can't be used as revision identifiers. However, you can query a job to find a changelist number, then use the changelist number to refer to file revisions:


p4 fixes -j NightlyBuilds

job NightlyBuilds fixed by change 1245 on 2004/02/18

This tells us that if we want to restore the nightly build configuration as of February 18, 2004, we should use @1245 as the revision identifier. For example:


p4 sync //depot/project/...@1245

Note that jobs can be associated with more than one changelist number. This means that you can use the same job to mark snapshots of recurring configurations. For example, the NightlyBuilds job can be fixed with a new changelist every night. At the end of the week, you'd have a list of snapshot revisions you can use to refer back to the nightly build configurations:


p4 fixes -j NightlyBuilds

job NightlyBuilds fixed by change 1245 on 2004/02/18

job NightlyBuilds fixed by change 1301 on 2004/02/19

job NightlyBuilds fixed by change 1384 on 2004/02/20

job NightlyBuilds fixed by change 1420 on 2004/02/21

job NightlyBuilds fixed by change 1532 on 2004/02/22

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 6: Controlling and Automating Activity

Inhaltsvorschau

Now that you've seen the nuts and bolts of how Perforce works, it's time to look at ways to control and automate what it does. This chapter focuses on aspects of control and automation, starting with a look at controlling depot and file access , including access to files in other Perforce domains. It describes using the depot to store specs as versioned files and restoring specs from saved versions. It describes setting up automatic change notification, and demonstrates how users can monitor depot activity. It offers tips on using Perforce in scripts, explains how scripts can mine for data efficiently, and touches on using triggers to invoke scripts. Lastly, it surveys the behind-the-scenes Perforce client programs with an eye to bringing even the most reluctant developers into the SCM fold.

We don't intend for this book to cover Perforce system administration, but there is one place where system administration overlaps with what this book is about, and that is where it concerns access to depots and depot files. Only Perforce superusers can create depots and control file access. We'll assume that you're a superuser.

In a brand-new Perforce installation, every user is a superuser until one of them runs protect. The first user to run protect becomes the one and only superuser, and only he or she can change other users' access to files. This is not as limiting as it sounds; the first superuser can also make other users superusers. For the complete details of how this works, see the "Protections" chapter in the Perforce System Administrator's Guide.

As you read earlier, the root of a file tree in the Perforce repository is a depot. (And yes, the entire repository is often called "the depot.") Perforce comes with one depot by default; its name is "depot" and its path is //depot/....

There can be more than one depot—that is, more than one file tree root—in a repository. As a Perforce superuser, you can create new depots with the depot command. For example, to create a depot called "Ace":


p4 depot Ace

 

Depot               Ace

Type                local

Addres              local

Map                 Ace/...

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Depot and File Access

Inhaltsvorschau


p4 depot Ace

 

Depot               Ace

Type                local

Addres              local

Map                 Ace/...

Just save the form as is to create a normal depot. Now users will be able to add files in the //Ace/... depot path.

To list your depots:


p4 depots

Depot Ace  2004/08/01 local Ace/...  'Created by super'

Depot depot 2004/04/11 local depot/... 'Default depot'

To delete an empty depot:


p4 depot -d depot

(Perforce won't let you delete a depot if files have already been submitted to it. To get rid of it you'll have to obliterate its files first. Alternatively, you could simply use depot protections to hide it from view.)

In Perforce, access to depot files is controlled by the protect command. Running the protect command opens up a form that keeps track of users, the files they can access, and the types of commands they can run. Here's an example:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Accessing Files in Other Domains

Inhaltsvorschau

As you know, a Perforce Server manages a repository and a database. These three things together—the server, its repository, and its database—can be thought of in the abstract as a domain. When you run a P4 command or launch a Perforce GUI program, you are entering a Perforce domain. Your username is checked against the list of users authorized for the domain. If you create a client workspace, its name—which must be unique in the domain—is added to the domain. Likewise, if you create files, their names—which must be unique within the domain—are added to the domain. Labels, jobs, branch views, and depots are also objects that can defined within the domain. Descriptions of all of the objects in the scope of a domain are stored in the domain's database, and versions of all the files in a domain are archived in the domain's depots.

In large companies, independent business units are likely to install and host their own Perforce domains . A Perforce feature called remote depots can be used to make one domain's versioned files visible in another.

Note that you don't need the remote depot feature to switch between Perforce domains. Perforce users can enter any Perforce domain, as long they have authorization and network access to it, by changing their P4PORT settings. (See Appendix A for an example of how P4PORT is used.)

But habitual switching between Perforce domains can be awkward. For example, say Bob normally works in the pilot:1666 domain—that is, his P4PORT is set to pilot:1666. (See Figure 6-1.) Every now and then he sets P4PORT to scout:1666 to get access to files in the scout:1666 domain. The user bob and its client workspace BobWS are instantiated as objects in the database of each domain.

Figure 6-1: Working in two Perforce domains

Unfortunately, the Perforce Servers at pilot:1666 and scout:1666 know nothing about the users and workspaces in one another's domain. Each Perforce Server guides Bob's activities as if the other domain didn't exist. If Bob synchronizes his workspace while connected to scout:1666, he could inadvertently overwrite files that came from

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Saving and Restoring Specs

Inhaltsvorschau

Specs, the Perforce database structures that represent workspaces and other nonfile objects, aren't normally versioned. However, they can be, if you set up a spec depot. A spec depot is managed entirely by the Perforce Server; it's used solely to store specs .

To set up a spec depot, use the depot command to create it This gives you a form to edit; enter "spec" in the Type field of the form. For example, to set up a spec depot named "specs":


p4 depot specs

 

Depot          specs

Type           spec

Once you've saved this form, your spec depot will be created. (Note that you have to be a Perforce superuser to create depots.)

From now on, every time a spec for a label, client, user, or any other object is saved, a copy of the spec form will be saved to a file in the spec depot.

You can use the Perforce Proxy to extend a single Perforce domain to the far reaches of your network. The proxy—which behaves just like a Perforce Server, as far as client programs can tell—builds up its own cache of depot files. It gives its nearby developers much faster access to files than they'd have if they connected directly to the Perforce Server.

At each geographic location, a Perforce Proxy runs on a machine easily accessible to developers there. Developers near the domain's hub connect their client programs directly to the Perforce Server, while developers at distant locations connect to a Perforce Proxy. The figure shows an example.

Figure :

For more information about the Perforce Proxy, see the Perforce Administrator's Guide.

Neither the Perforce Server's remote depot feature nor the Perforce Proxy costs extra, by the way. Your company pays for the same number of Perforce users regardless of how your depots, domains , and proxies are configured.

You can restore a deleted or badly edited spec from the last good revision of the corresponding file in the spec depot.

For example, we'll restore a job named job000123. First we look for the spec's file in our specs depot:


p4 files //specs/...job000123...

//specs/job/job000123.p4s#4 ...

Next we check the recent history of the file:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Change Notification and Change Monitoring

Inhaltsvorschau

Perforce has some commands and features that are especially useful for change notification and change monitoring .

A change review daemon is a script that runs continuously to check for recent depot changes and notify interested users about them. Perforce provides a sample change review daemon, written in Python. To download it, go the Perforce Software website (http://www.perforce.com) and navigate to Downloads → Related Software → Review Daemons. The script is p4review.py.

The p4review.py script contains a few simple instructions for installing and starting it up. Once it's running, it sends change notification email that looks like:


From          sue@ace.com

To            don@ace.com

Subject       PERFORCE change 1254 for review

Message       Change 1254 by sue@sue-ws 2005/01/28 13:30:20

 

                       Fix highlighting on active items so that

                       even when all are lit you can where the

                       borders are.

 

               Affected files ...

 

               ... //Ace/DEV/gui/active/mlpen.cpp#9 edit

               ... //Ace/DEV/gui/active/fmgr.cpp#3 edit

Note that the mail appears to come from the person who made the change. If Don replies to this message, for example, his reply will go to Sue.

To receive email from p4review.py you can use the user command to subscribe to the depot paths you're interested in reviewing. (in other words, the depot paths you want to hear about when changed.) The user command gives you a spec form to fill out. In its Email field you can give an address to which notifications should be sent, and in the Reviews field you can list depot paths you're interested in. Here, for example, is how Don's user spec is set up:


p4 user

 

User            don

Fullname        Don Quixote

Email           don@ace.com

Reviews         //Ace/DEV/gui/...

                //Ace/MAIN/gui/...

Don will receive a p4review.py-generated email message for each change that affects files in the //Ace/DEV/gui and

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Scripting Tips

Inhaltsvorschau

As you may have gleaned from what you're read so far, and as you'll certainly see in the chapters that follow, there are some very useful things you can do with hard-to-type P4 comands and P4Web URLs. Scripts, of course, can hide complicated syntax and command sequences. Scripts have an even more important role, however, and that is in customizing and automating your SCM procedures. In the subsections that follow are a few tips to get you started using P4 commands in scripts.

Many Perforce commands—files and opened, for example—give you abridged information about files. The fstat command gives you everything, and its output format is easier for scripts to parse. For example:


p4 fstat //public/revml/vcp.pl

... depotFile //public/revml/dist/vcp.pl

... headAction add

... headType xtext

... headTime 1079646286

... headRev 4

... headChange 4235

fstat has a cornucopia of flags that control the scope and detail of its output. See the Perforce Command Reference for details, or run this command:


p4 help fstat

for more information.

Almost any Perforce command can produce output as verbose as fstat's if you use the -ztag flag on p4. For example:


p4 -ztag describe 4417

... change 4417

... user barrie_slaymaker

... client VCP_barries_winXPpro_dev

... time 1092971510

... desc - Adapt to "estimated values" messages

       - Adapt to more accurate test suite

... status submitted

... depotFile0 //public/revml/bin/gentrevml

... action0 edit

... type0 xtext

... rev0 56

... depotFile1 //public/revml/lib/VCP/TestUtils.pm

... action1 edit

... type1 text

... rev1 65

(Compare this to the readable but difficult-to-parse output shown in the depot browsing examples in Chapter 1.)

For more information on tagged output, run:


p4 help usage

p4 help undoc

You can make p4 marshal its tagged output for Ruby or Python. For example, p4 -R produces marshalled Ruby output:


ruby -e "p Marshal.load( `p4 -R describe 4417` )"

{"action3"=>"edit", "status"=>"submitted",

"user"=>"barrie_slaymaker", "action4"=>"edit",

"time"=>"1092971510", "code"=>"stat", "type0"=>"xtext",

"depotFile0"=>"//public/revml/bin/gentrevml",

"client"=>"VCP_barries_winXPpro_dev", "type1"=>"text",

"depotFile1"=>"//public/revml/lib/VCP/TestUtils.pm",

"change"=>"4417", "type2"=>"text",

"depotFile2"=>"//public/revml/t/91cvs2revml.t",

"rev0"=>"56", "desc"=>"- Adapt to \"estimated values\" messages\n

- Adapt to more accurate test suite\n",

"type3"=>"text", "depotFile3"=>"//public/revml/t/91vss2revml.t",

"rev1"=>"65", "type4"=>"text",

"depotFile4"=>"//public/revml/t/95cvs2p4.t", "rev2"=>"16",

"action0"=>"edit", "rev3"=>"7", "action1"=>"edit",

"rev4"=>"30", "action2"=>"edit"}

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Behind-the-Scenes Version Control

Inhaltsvorschau

—Anonymous
"Don't bore me with 'client' and 'sync'—just give me the blinkin' file!"

While we may agree among ourselves that it's all software and we're all software developers, not everyone we work with does. We're all software developers until it's time to learn how to use version control , at which point some of us suddenly become artists, lawyers, or chief executives with no head at all for technical details.

For these busy Luddites, behind-the-scenes version control can gently encourage SCM participation. It lets them access and update Perforce files using applications familiar to them—like Microsoft Word—with commands they understand—like "Save." In this section we'll take a look at the Perforce components that can be set up to work behind the scenes.

WebKeeper is a Perforce module that can be compiled and linked into the Apache HTTP Server. With WebKeeper in place, a file in the depot called //Ace/WEB/index.html can be accessed from a web browser with a URL like:


http://intranet.ace.com/Ace/WEB/index.html

(This example assumes that Apache is configured at port 80 of a machine called intranet.ace.com, of course.)

When a web browser sends Apache a URL, Apache checks its configuration parameters to see wheather the URL refers to Perforce content. If it does, it lets its WebKeeper module convert the URL to a depot filename and fetch file content from the Perforce depot. Apache then sends the file content back to the user's browser. The depot files served up by WebKeeper are entirely under the control of Apache—to Apache, the depot looks like a file system. You can use the same redirects, path aliases, and authentication for depot files as you would for any other files managed by the Apache server.

Like WebKeeper, the P4Web viewer lets you access a file in the depot called //Ace/WEB/index.html with a URL like:


http://intranet.ace.com/Ace/WEB/index.html

And, as you read previously, there are P4Web URL tricks you can use to link to all kinds of Perforce information. None of these tricks will be of much use to naïve or reluctant Perforce users, of course. However, they can be of great use to Perforce-savvy project leads and configuration managers—P4Web URLs inserted into web pages and email can give naïve users a portal to information they would otherwise be oblivious to.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 7: How Software Evolves

Inhaltsvorschau

Just as there's more to driving than knowing how to operate a car, there's more to SCM than knowing how to use an SCM tool. Mastering SCM starts with understanding how software evolves and recognizing how team collaboration, defect management, parallel releases, and distributed development affect the software life cycle. For just as road maps and rules of the road are the bigger part of driving, the software life cycle is the bigger part of SCM.

In this chapter we take a step back from Perforce to look at the roadmap of the software life cycle: the mainline model. We'll identify the codelines that form the mainline model and describe the rules of the road for change flowing between them. This chapter sets the stage for the chapters that follow, each of which demonstrates using Perforce to manage codelines of a particular type.

Consider the story of Ace Engineering, a fictitious software company. After a year of intensive startup development, the company introduced a new product, AcePack1.0. Sales were successful: the customer base grew. Alas, so did the bug report database. Within six months Ace had produced a point release—essentially the same product but with many bug fixes and small enhancements—as AcePack1.1. For a while, the company supported customers on either version, but at the end of the second year it announced that AcePack 1.0 was being discontinued.

During this time Ace developers had started working on two new features, code-named Saturn and Pluto. The plan had been to include both features in the AcePack 2.0 release. Midway through the third year Pluto was done, but Saturn turned out to be much more work than anticipated. (In fact, the company ended up doubling the size of the Saturn development team, with half the team working on an unforseen adjunct now code-named Saturn Plus.) AcePack 2.0 was ultimately released without the Saturn feature.

The 2.0 release did well, although it too had its share of problems. It was hard to get customers to upgrade, and Ace ended up having to fix showstopping bugs in both available releases, 1.1 and 2.0. However, it was able to produce a very stable release, AcePack 2.1, about six months later. Shortly after that, support for AcePack 1.1 was discontinued.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

The Story of Ace Engineering

Inhaltsvorschau

Finally the Saturn and Saturn Plus development projects were completed. The Saturn feature will be in AcePack3.0. Meanwhile, customers have upgraded to AcePack 2.1, AcePack 2.0 has been retired, and Ace developers have started working on yet another new feature, codenamed Rocket. (Figure 7-1.)shows the development history of Ace's product.

Figure 7-1: Ace Engineering's first five years

The Ace Engineering story illustrates typical problems of the software life cycle:

At any point in time there is likely to be more than one supported product version available to customers. Ace must be prepared to field customer calls, diagnose problems, and fix critical bugs in all of their currently supported versions.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

The Mainline Model

Inhaltsvorschau

A codeline is, for the most part, the same as a branch. But though the term branch can mean any set of files created by branching, codeline is imbued with slightly more significance. Codelines have a purpose, a strategic role in the development of software. Together, codelines form a model of software evolution.

In the Perforce view of software configuration management, one model—the mainline model—is most effective. This chapter discusses codelines and software evolution in the context of the mainline model. It's not a Perforce-specific discussion, by the way—the mainline model is a general concept, not a Perforce feature. But it is the concept on which much of the design of Perforce is based.

In the ideal world, there are no bugs, no schedule crunches, no personnel changes, no market shifts, and no technology revolutions. Software in the ideal world is simply developed and released—that is, new features are developed, and when they're ready, a new version of the software is released (see Figure 7-2.). Each release contains features that work perfectly.

Figure 7-2: The mainline in the ideal world

If there were such an ideal world, we probably wouldn't need an SCM system. Even so, we'd have a collection of files evolving together in a codeline. This codeline embodies the evolution of our software; it is our mainline. In the ideal world it would be the only codeline we'd ever need.

A sad fact of the real world is that the software we develop isn't perfect. Because of that, we subject software to a testing phase before release, during which bugs are invariably found. We could do all this in the mainline if development could halt for the testing phase, and if all bugs could be found and fixed during testing. But all bugs are not found during testing; many are found after software is released. And we can't hold off on new development during the testing phase because we have deadlines and market pressures to face. So we branch completed software from the main codeline into a release codeline.

Branching release codelines allows us to do two different kinds of software development at once. One kind is bug fixing—euphemistically known as

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Ace Engineering Revisited

Inhaltsvorschau

Let's look at the mainline model as employed by Ace Engineering. Once an initial body of development was begun, it formed the MAIN codeline. As you read, the first AcePack versions released were 1.0 and 1.1. However, Ace engineers did not plan their schedule around two first-generation (1.X) releases. In fact, they didn't know how many 1.X releases they would make. Their strategy was simply to make periodic point releases to fix bugs and tidy up loose ends until the next major release was ready. To support the as-yet undetermined number of 1.X releases, MAIN was branched into REL1 (see Figure 7-17)

Figure 7-17: REL1 branched from MAIN

AcePack 1.0 and AcePack 1.1 were released from the REL1 codeline. REL1 was used for ongoing fixing before and after the releases were made. When AcePack 1.0 customers required patches, the AcePack 1.0 version of the REL1 codeline was branched into R1.0. (see Figure 7-18.) The only changes allowed in R1.0 were fixes for critical, showstopping bugs; these were immediately merged into REL1. Thus, when AcePack 1.1 was released, all the R1.0 fixes were already in it. The same strategy was used to patch AcePack 1.1—the REL1 codeline was branched into R1.1. No changes except for critical fixes were allowed in R1.1, and all R1.1 changes were merged immediately into REL1. Meanwhile, changes in REL1 were regularly merged to MAIN; thus the mainline always reflected the sum of improvements made in the 1.X releases.

Figure 7-18: The 1.X release branches

R1.0 and R1.1 were fairly inactive codelines. Their entire purpose was to provide a place to fix showstopper bugs in released versions. As a result, neither R1.0 nor R1.1 deviated very much from their parent, REL1, and merging changes from them into REL1 was extremely easy.

You may be wondering why Ace used separate R1.0 and R1.1 codelines to patch released products instead simply building patched releases from REL1. The reason is that while the releases were concurrently supported, developers had to be able to deliver critical bug fixes to both releases without requiring customers on either release to upgrade. (Ace Engineering is a very accommodating company.) And if you're wondering what REL1 was used for after R1.1 was released, recall that Ace engineers were not sure how many 1.X releases they would make. If all went well, the new features for the next major release would be ready soon and the REL1 codeline could be abandoned. But on the chance that the new-feature schedule would slip, developers continued fixing bugs in REL1 and merging their fixes into MAIN. That way they would have yet another 1.X point release ready to go if no 2.0 release were forthcoming.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Containerizing

Inhaltsvorschau

In commerce, manufacturers control complexity by "containerizing ." A truck driver doesn't know he's delivering 19 sofas, 400 chairs, and 80 tables to outfit a hotel in New York. All he knows is that he's delivering one shipping container from the factory to the shipyard. And when he arrives at the shipyard, he doesn't throw open the back of the truck and start counting out sofas. He merely checks that the container is intact.

It's the same with branching and merging. The software we're working on involves far too many files for us to have to branch and merge them individually. We need to containerize so we can branch and merge mere handfuls of containers instead of hundreds of thousands of files.

Although they seem to have different names everywhere they're used, the file containers essential to software development are modules, codelines, and—for lack of a better term—bodies of code.

The files we work on are grouped into modules. At face value, a module is simply a set files organized in a directory tree. (Other systems, and other writings on the topic, use terms like source directory, component, and subsystem for what we're calling a module.) What makes modules important is that they correspond to the file hierarchies needed on disk in order to work on specific parts of the software being developed.

In the development of the AcePack software, for example, the GUI module corresponds to the directory tree of C++ source files and Jamfiles needed to build AcePack's GUI components. In order to work on the GUIs, a developer needs this directory tree on disk. Other modules support other areas of development. The database module, for example, contains the scripts and stored procedures needed on disk to work on AcePack's database component. The documentation module contains Frame files and generated HTML files for the AcePack manuals. The utilities module contains AcePack-specific scripts and configuration files common to all development tasks. (See Figure 7-24.)

Figure 7-24: Top-level modules

Modules can contain other modules as well. For example, the AcePack GUI module is subdivided into a module of common code and a module for each of the AcePack GUI tools. The documentation module is subdivided into modules for each AcePack manual plus a module containing the tools used to build them. (Figure 7-25.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 8: Basic Codeline Management

Inhaltsvorschau

This chapter introduces conventions, policies, and techniques for managing codelines in a Perforce system. It also describes common pitfalls and missteps of codeline management that can easily be avoided.

You know by now that the Perforce depot is a hierarchical structure of directories and files, and that you are at liberty to organize it as you please. The question is, what is the best way to organize it? There is no one right answer, of course, but some factors and recommendations should be taken into consideration as you decide what goes where.

Interestingly, Perforce doesn't know about containers like bodies of code, codelines, and modules. However, in Perforce we can containerize, and we do, with filespecs. Any set of files that can be described with a single filespec can be treated as a container with a life and a history of its own. Filespec-defined containers can be used in activities like navigating a depot tree, setting up a workspace, making a branch, and configuring a release. This, in turn, lets us treat these containers as true SCM objects—that is, as objects that can be versioned, compared, branched, merged, labeled, and restored.

For example, //Ace/REL1/... is the filespec that refers to Ace's Release 1 codeline. You can use this filespec to do things like display its recent history:


p4 changes -m3 //Ace/REL1/...

Change 9634 ... bob  'Fix installer ...'

Change 9632 ... bob  'Rebuild zip file...'

Change 9629 ... doug 'New screenshots...'

You can also refer to the REL1 codeline by revision. For example, to compare two of its revisions, use:


p4 diff2 -q //Ace/REL1/...@9634 //Ace/REL1/...@9629

This is all fairly easy, and in the next chapter we'll see quite a few more examples. (Our examples are admittedly simple—it's easy to remember //Ace/REL1. In real life, the filespec you'll need to use is likely to be a little less self-evident.)

Module filespecs work the same way. For example, doc is a top-level module in the REL1 codeline. It can be referenced with the //Ace/REL1/doc/...

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Organizing Your Depot

Inhaltsvorschau

For example, //Ace/REL1/... is the filespec that refers to Ace's Release 1 codeline. You can use this filespec to do things like display its recent history:


p4 changes -m3 //Ace/REL1/...

Change 9634 ... bob  'Fix installer ...'

Change 9632 ... bob  'Rebuild zip file...'

Change 9629 ... doug 'New screenshots...'

You can also refer to the REL1 codeline by revision. For example, to compare two of its revisions, use:


p4 diff2 -q //Ace/REL1/...@9634 //Ace/REL1/...@9629

Module filespecs work the same way. For example, doc is a top-level module in the REL1 codeline. It can be referenced with the //Ace/REL1/doc/... filespec. To see its recent history, for example, use:


p4 changes -m3 //Ace/REL1/doc/...

You can also refer to the doc module irrespective of the codeline, as long as it has a fixed location relative to the root of the codeline. For example, you overheard Doug saying he just checked in some great new diagrams. You don't know which codeline he checked them into, but you know they'll be in the

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

General Care and Feeding of Codelines

Inhaltsvorschau

In the chapters that follow, you'll see how to create and manage specific types of codelines. But first, let's begin with some general information about managing codelines with Perforce.

Every codeline needs a curator. We say "curator" instead of "owner" because often codelines are owned collectively. But even a collectively-owned codeline should have a single point-person to keep an eye on housekeeping tasks. This person may delegate tasks to others, but making sure the tasks get done is his or her responsibility.

Some of the codeline curator's tasks require special privileges. In particular, the tasks involving protections and triggers require superuser access, although these aren't tasks that are done often. As you plan codeline management, be prepared either to grant superuser access to codeline curators or to have someone with superuser access on hand who can run commands on behalf of codeline curators.

As far as Perforce is concerned, you're at liberty to use any name you want for a codeline. Bear in mind that:

You'll use the codeline's name for its depot path and various other Perforce objects. The name should conform to your depot path naming rules.
You can't easily change a depot pathname once you've created it.
It's nice when a codeline's name can be used in conversation. So instead of using an inscrutable, data-derived string as a codeline name, consider using a pronounceable, recognizable nickname.
Codelines can be reused. If you're planning on reusing a codeline, give it a name that describes its general scope, or that's not tied to any particular use.

The mainline typically contains many more modules than you'll need to branch into a single development or release codeline. In the following chapters you'll read about how a codeline's purpose dictates (or suggests) the modules to branch into it. In the meantime, bear in mind that:

Modules in a given codeline are either "active" or "static." The active modules are the ones developers are working on—they're evolving right there in the codeline. The static ones aren't evolving in the codeline at hand—they've been branched to support development. (Inactive modules may be evolving in other codelines , though; the codeline at hand may need to be updated with their latest versions.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Nightly Builds

Inhaltsvorschau

The firmer a codeline is, the more likely it is that you'll be setting up a nighty build of the software in it. (Although we call it a nightly build , we mean any recurring, automated process that resynchronizes and rebuilds.) In this section we'll look at how a nightly build script can use Perforce to synchronize a workspace with a codeline, open and submit generated files, and label the codeline.

Nightly build workspaces are used by build engineers and their build scripts. A a rule of thumb:

Each combination of codeline and target platform should have its own nightly build workspace.
Each nightly build workspace should have a view of one and only one codeline.

At Ace, for example, a workspace called REL1-bld-linux is dedicated to the nightly builds of the REL1 codeline on Linux:


p4 client REL1-bld-linux

 

Client      REL1-bld-linux

Root      /usr/builds/REL1

View      //Ace/REL1/...   //REL1-bld-linux/...

The first thing the nightly build script should do before synchronizing is to revert files that may have left opened by a previous, failed build:


p4 revert //...

(The only files likely to be opened are generated files that will be submitted by the script. However, opened files can't be resynchronized and unsynchronized files can't be submitted, so they should be reverted first.)

Next, your build script should identify the snapshot of the depot revision is it building. This is the build ID; it's the highest changelist number in the depot at the start of the build cycle. Your build script can get this number from the output of changes -m1:


p4 changes -m1

Change 7089 on 2005/01/21 by mei 'Fix size of pop-up for...'

If you trust your build tools to do incremental builds correctly, synchronizing the nightly build is easy. All the script has to do is synchronize with the build ID:


p4 sync @7089

Each time the workspace is synchronized this way, the only files that are updated are those that have changed since the last build; populating a nightly build area is very efficient if only a few files have changed and little needs rebuilding.

If, on the other hand, your build tools can't be trusted to rebuild things 100% correctly when files are updated, your nightly builds will have to be done from scratch. And for scratch builds, the build script will have to ensure that the workspace is pristine at the start. The simplest way to assure this is to remove workspace files by brute force, then force Perforce to resynchronize the entire workspace. For example, in a Unix workspace whose root is

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Is Bug X Fixed in Codeline Y?

Inhaltsvorschau

When a codeline is branched, a new variant of the software it contains is born. As work proceeds, changes are submitted independently to each codeline and, depending on how and when changes are merged between them, the variants diverge. Eventually each variant becomes distinct in its quality and functionality. Sooner or later the question is bound to come up, "Is bug X fixed in codeline Y?"

In simple cases, branching diagrams can reveal the answer. It's easy to see that if a bug is fixed in one codeline at some point in time, the same bug will be fixed in any codeline subsequently branched from that codeline, as illustrated in Figure 8-3. But what about the case where a bug fix is merged from one codeline to another? What if several bug fixes are merged together? What if the fix was backported to a distantly related codeline? In a production development environment, where there are many codelines and many merges, branching diagrams would show so many relationships that the end result would be impossible to interpret.

Figure 8-3: The ramifications of a bug fix

Perforce, it turns out, is innately capable of answering the question, "Is bug X fixed in codeline Y?" Under the right conditions, a merged bug fix can be detected regardless of the codeline it originated in, how many intermediate codelines it passed through, when it was merged to each codeline, and the sequence in which it was merged before reaching the codeline in question. Using integration records stored in its database, the Perforce Server can detect trails of merges emanating from file revisions associated with changelists. A bug fixed in one codeline and merged to a second, third, and fourth codeline, for example, leaves just such a trail of merges.

In this section we'll look at how Perforce detects merged bug fixes, and the factors that make detection more accurate.

Before looking at the logic behind Perforce's bug fix tracking ability, let's take a look at some of the objects modeled in the Perforce database. We'll start with the changelist. Submitted changelists are recorded in the Perforce database when users submit files. The submitted changelist object associates file revisions with a changelist. For example:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 9: Release Codelines

Inhaltsvorschau

It's June, the mainline abounds with completed development, and it's time to branch a new release. In this chapter we take a look at the care and feeding of release codelines .

We'll use Ace Engineering's repository for our examples. In fact, we'll put ourselves in the role of Ace Engineering's release manager for the example scenario that runs through the chapter. The filespecs of interest to us are:

//Ace/MAIN/...: The mainline
//Ace/REL1/...: The codeline that supports our 1.X releases
//Ace/REL2/...: The codeline we're going to create and use for our second major release

The top-level modules that make up our release codelines are:


db/...

built/...

doc/...

gui/...

tests/...

utils/...

(Remember, these names, paths, and filespecs are shorter than you're likely to need in the real world. We keep them short here so the examples fit on the page.)

In preparing to branch the new release codeline, we'll create a branch view and a label view, label the modules we're going to branch, and set up a master workspace. Before doing any of these things, however, we have to decide when to branch the codeline, what to call it, who owns it, and what belongs in it.

As you read in Chapter 7, the mainline leaps (or creeps) forward with changes delivered from development codelines. When our development goals have been reached, we make a release.

Of course, software must be stabilized before it is released. (That is, it has to be tested, its showstopper bugs have to be fixed, and its loose ends have to be tied up.) We can't stabilize a release in the mainline because the mainline must remain open for new development. The point at which new development conflicts with release stabilization work, therefore, is the point at which we branch a release codeline.

The curator of the release codeline is typically the release manager, the person in charge of getting the release out the door. Every change to the release codeline is going to affect the release manager's schedule; it makes sense that the release manager controls the codeline.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Creating a Release Codeline

Inhaltsvorschau

As you read in Chapter 7, the mainline leaps (or creeps) forward with changes delivered from development codelines. When our development goals have been reached, we make a release.

Every company has its own system for naming releases. Perforce doesn't impose any kind of release naming. In fact, visible release numbering systems have very little bearing on how software is managed in Perforce. We can pick any name we want for a release codeline without constraining externally chosen release identifiers.

At Ace Engineering, we take the following into account:

We may not know the exact ID of the release we're working on. Even if we do, the final release number may change in the course of stabilization. (For example, we may be planning to release AcePack 2.0.0, but by the time we get there, it could be AcePack 2.0.3. Or UltraPack 2.0.3, for that matter.) This is a good reason not to use the actual, intended release ID as a codeline name.
A single codeline can be used for a series of incremental releases. (For example, we'll be releasing AcePack 2.0-Beta and AcePack 2.1 from our new codeline. And we may produce point-releases—AcePack 2.1 and so forth—from the same codeline.) This is another reason a specific release ID isn't suitable for a codeline name.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Working in a Release Codeline

Inhaltsvorschau

The release codeline exists in order to perfect already-developed software. It is typically used to test thoroughly, fix bugs, finalize installers and documentation, and generally to tie up loose ends. Although these things may involve changes to program source files, these are small changes—no refactoring, and no changes to intended functionality. What all this adds up to is that development in the release codeline is a matter of close collaboration between coders, tech writers, testers, the build czar, and the release manager.

Now, if you'll take off your codeline curator hat and put on your software developer hat, we'll talk about points pertinent to working in a release codeline.

The people working on releases are on very tight schedules, and release codelines are held to high levels of quality. In the grand scheme of things, release codelines are at the top of the tofu scale. You, as a developer, don't want to be the one to throw a wrench in the works by checking in mismatched files or untested changes. You can reduce the chance of that happening by dedicating a workspace to release stabilization work.

To work on stabilizing REL2, for example, set up a workspace dedicated to working in REL2. You can use the REL2-master workspace as a template, as we'll see in a moment. This gives your workspace a view that encompasses all the REL2 modules you'll need on disk in order to build and test your changes.

For example, Sue is going to create a workspace called REL2-sue for her REL2 bug fixes. Sue is working on Unix; the workspace will be rooted in her /usr/team/sue/REL2 directory. Of the modules in the REL2 codeline, Sue needs only the doc and utils modules on disk for her work.

Sue creates a client spec using the REL2-master workspace as a template. The client command gives her a spec form to edit. The form comes prefilled with a list of REL2 modules in its View field. She edits the form, entering her workspace root and removing the view lines for the modules she doesn't need:


p4 client -t REL2-master REL2-sue

 

Client          REL2-sue

Root            /usr/team/sue/REL2

View            //Ace/REL2/doc/...    //REL2-sue/doc/...

                //Ace/REL2/utils/...  //REL2-sue/utils/...

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Integrating Changes into the Mainline

Inhaltsvorschau

Developers, you're not off the hook once you've submitted bug fixes to the release codeline. Your changes need to be integrated from the release codeline into its parent. In this section we take a look at what you need to know and do to integrate your changes.

All changes in the release codeline should be integrated into the mainline. This is almost always safe because release codelines are inherently more stable than their parents. When it's not not safe is when the mainline has evolved so much since the release was made that massive architectural differences make it difficult or impossible to merge files. In "How much has the mainline changed?" a bit later in the chapter we'll look at how to gauge the feasibility of an impending integration.

Even when a release codeline change has no relevance to the mainline—it updates release-specific configuration files, for example—it should be integrated to the mainline. It can be resolved by ignoring the change. As you read in Chapter 4, This creates integration history that shows that the change has been at least accounted for, if not actually merged, in the mainline.

Ideally, changes should be integrated to the mainline as they occur. In practice, there's always an interval of uncertainty between the time a change is submitted to a release codeline and the point at which it's proved valid. The reality is that each change should be integrated as soon as it's validated.

The best person to integrate a change to the mainline is the person who made the change in the release. Why? Because the person who made the change understands the content of the files involved. If there are any conflicts to resolve, he or she will know how to resolve them. If there are problems with compiling or testing, he or she will know how to fix them.

To integrate your changes to the parent codeline, you'll need a workspace with a view of the parent codeline. The procedure shown in "The developer's workspace," earlier in the chapter, works to set up a workspace for the parent codeline as well. Sue, for example, sets up her MAIN-sue workspace as follows:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Making a Release

Inhaltsvorschau

Once a release codeline is stabilized—or stable enough, at any rate—we can make the release. ("We," in this context, refer to the release manager and release codeline curator.)

The release should be built from a cotemporaneous snapshot of the release codeline. In other words, the files that contribute to the release should be the head revisions as of a known point in time. Moreover, they should all come from the release codeline. (Mixing and matching codelines to build a release just invites confusion.)

A known point in time in Perforce equates to a changelist number, of course. The changelist number that identifies the snapshot of our first release out the REL2 codeline is 8901, as shown in Figure 9-1

Figure 9-1: The release snapshot

The filespec //Ace/REL2/...@8901 is the comprehensive, permanent, and unambiguous reference to the files that went into the release.

It's not entirely necessary to label a release, but labels do have their advantages. For one thing, they have recognizable names, whereas changelist numbers don't. A label can be used to associate an external release identifier with a filespec.

The release we're making happens to be known to the rest of Ace Engineering as AcePack_2.0-Beta. To label our new release, we run:


p4 tag -l AcePack_2.0-Beta //Ace/REL2/...@8901

The revision @AcePack_2.0-Beta can now be used in place of a changelist number to identify files in the release (see Figure 9-2.)

Figure 9-2: The release label

For our own reference, we can note the release point in the label description. We use the label command to bring up the label spec form, note the release snapshot changelist number in the Description field, and enter the release codeline's filespec in the View field:


p4 label AcePack_2.0-Beta

 

Label            AcePack_2.0-Beta

Description            Built from @8901

View            //Ace/REL2/...

This is for documentary purposes only; changing the label spec does not affect the configuration already tagged with the label.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Distributing Releases

Inhaltsvorschau

At Ace Engineering, software is distributed to customers via FTP—the software is put on an external FTP site; customers use FTP to download it. The FTP site is simply a Perforce workspace kept constantly synchronized with the DIST codeline in the Ace's depot.

The DIST codeline is Ace's distribution stream. Its sole purpose is to control the software currently available to customers. Distributing a release at Ace Engineering, therefore, is a matter of copying built components from release codelines to the distribution stream. In the depot, Ace's distribution stream is in the //Ace/DIST path.

At this point, software in our REL2 codeline has been stabilized, finalized, built, and tagged with the AcePack_2.1 label. (By "built" we mean that all of the built components have been checked in to the release codeline itself.) At Ace, built files and installable objects are contained in the built module of each codeline. Of these, the files we'll be delivering to the distribution stream are:


//Ace/REL2/built/bin/win32/ap.zip

//Ace/REL2/built/bin/linux/ap.tar

These files will be copied from //Ace/REL2/built to //Ace/DIST/AcePack into files whose names identify the release. This is normally done by a script controlled by the release engineer, but for illustration, we'll do it manually.

Since we're going to be submitting files into the DIST codeline, we'll have to use a client workspace whose view includes the //Ace/DIST path. We've got that set up here, using a workspace called DIST-update :


Client            DIST-update

View            //Ace/DIST/...  //DIST-update/...

Now, using the DIST-update workspace , we copy the necessary files, using the AcePack_2.1 label to make sure we get the right ones:


p4 integ -d \

   //Ace/REL2/built/bin/win32/ap.zip@AcePack_2.1 \

   //Ace/DIST/AcePack/bin/win32/ap2.1.zip

p4 integ -d \

   //Ace/REL2/built/bin/linux/ap.tar@AcePack_2.1 \

   //Ace/DIST/AcePack/bin/linux/ap2.1.tar

p4 resolve -at

p4 submit

(We use -d with integrate in case we're replacing files previously deleted from the distribution stream. The

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Breaking the Rules

Inhaltsvorschau

Despite the most meticulous planning, we occasionally have no choice but to defy the rules of the codeline road. In this section we'll look at two ways to break the rule that says change does not flow to a release codeline from its parent.

When you're supporting several releases at once, you may find yourself in a situation where a bug fix made in one release has to be backported to another. For example, Jody, of Ace Engineering's QA team, has detected a subtle but severe, data-corrupting bug during stabilization of the REL2 codeline. Ann, a developer responsible for the module in which the bug was found, fixed the bug in REL2 with changelist 8896. She then merged her fix to MAIN, using the procedure described in "Integrating Changes into the Mainline," earlier in the chapter. Change 8904 is the point at which REL2's change 8896 was incrementally integrated to MAIN. (The fact that the change was integrated incrementally is what's going to make this bug fix easy to backport.

Jody now tests the currently available release, AcePack 1.3. She finds that it too is affected by the bug, although the problem had not been detected before. The bug is serious enough to merit a 1.3.1 point release. For this, the bug fix is going to have to be backported into the REL1 codeline. This requires cherry-picking a change, either 8896 from REL2 or 8904 from MAIN, and integrating it to REL1, as shown in Figure 9-4.

Backporting either change will do the job, but integrating from MAIN to REL1 will be easier than integrating from REL2 to REL1. Why? Because at Ace, every release codeline has a branch view that reconciles its structure with its evolving parent codeline. (All the branch views follow the conventions described earlier in the chapter in "A branch view for the release codeline" and "Keeping the branch view up to date.") Because REL1 was branched from MAIN, there's a REL1-MAIN branch view. But there is no branch view that reconciles REL1's old structure with REL2's newer structure.

Figure 9-4: Choosing the change to backport

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Retiring a Release Codeline

Inhaltsvorschau

As you read in Chapter 8, you can retire a codeline by setting protections on its depot path. Before doing that, however, you should make sure no one's currently working in the codeline, and that all of its changes have been merged to its parent.

Before retiring a release codeline, make sure none of its files are checked out. For example, to see if any of REL1's files are still checked out:


p4 opened -a //Ace/REL1/...

(The -a flag extends opened's scope to files outside the current workspace.) You should contact these developers and let them know you're retiring the codeline. Once you set protections on REL1, they won't be able to check in their changes.

If you plan to use protections to hide a release codeline from view, you'll first have to make sure all changes are integrated from it to its parent. Once you hide it from view you won't be able to integrate changes from it. To see which of REL1's changes still need integrating to MAIN, use:


p4 interchanges -r -b REL1-MAIN

Any changes listed should be integrated before you set protections that hide REL1 from view. See "Integrating Changes into the Mainline," earlier in the chapter.

To prevent developers from submitting changes to a release codeline, restrict permission to read on the codeline's depot path. (Recall that you use the protect command to do this. See Chapter 6.) For example, to set read permission on REL1:


p4 protect

 

Protections            ...

                       read  user  *   *   //Ace/REL1/...

                       ...

This step prevents people from opening files in the //Ace/REL1 path. It doesn't prevent them from seeing the files, synchronizing with them, or branching from them, however.

There are a couple of reasons you might want to hide retired codelines altogether. One is that they'll show up in GUI file trees—the more retired codelines there are, the clumsier it becomes to navigate a file tree. The other reason is that the Perforce Server does less work if retired codelines are hidden from commands that scan the database.

You can hide a codeline from view by revoking list permission on it. Better yet, instead of revoking it, restrict the permission to a group no one is in. That way, anyone who does have a sudden need to see the codeline can be simply added to the group.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Task Branches and Patch Branches

Inhaltsvorschau

As you read in Chapter 7, release codelines can themselves be branched. For example, a release codeline can be branched into a task branch to isolate a risky bug fix. Or, to patch an already-released version, a release branch can be branched into a patch branch. What task branches and patch branches have the following in common:

Only a few files are actually changed.
No structural changes are involved.

It often makes sense to implement task branches and patch branches as sparse branches. A sparse branch contains only a handful of files rather than a full complement of modules. To work in a sparse branch you use a workspace client view to overlay the branch onto its parent codeline. You branch files as needed, instead of all at once at the outset. We'll look at how to do this in the subsections that follow.

A task branch is simply a short-lived, single-user codeline dedicated to a specific development task. Task branches are often used for fixing bugs in codelines too firm to allow developers to check in changes directly. As a developer, you create a task branch by branching the parent codeline; you make your changes in the task branch. This gives you a place to check in changes without affecting the parent directly, while giving reviewers a way to see what you have done. After your changes are approved, you can integrate them to the parent codeline.

For example, say Rob is fixing an AcePack bug known as BUG0422. The bug affects AcePack's database component. The fix will eventually go in the REL2 codeline, but Rob's going to submit it to a task branch first. Dee maintains the AcePack database code in released products. She will review Rob's fix, and if it passes muster, she'll integrate it into REL2.

At Ace Engineering, task branches are named after bugs. Rob's task branch will be called BUG0422; it will be located in //Ace/BUG0422. Figure 9-6 shows the timeline of the BUG0422 branch. It's very short.

Figure 9-7 shows the intended flow of change between the task branch and its parent, the release codeline.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 10: Development Codelines

Inhaltsvorschau

As you read in Chapter 7, development codelines provide a place to check in incremental work on projects without destabilizing the mainline. In this chapter, we look at creating development codelines, working in development codelines, keeping development codelines up to date, and delivering completed development work into parent codelines.

With the exception of the mainline, every codeline has a parent; the parent is the codeline it was branched from.

Creating a development codeline is a matter of creating a branch view and a master workspace, and using them as branching files. The curator of the development codeline does these things, after deciding what to name the codeline and which modules to branch. First we'll look at the factors and steps involved in creating a development codeline.

The purpose of a development codeline is to isolate potentially disruptive coding and to decouple project schedules. Ideally, we wouldn't need development codelines—all development would take place in the mainline, and when it was done, we'd make a release. Realistically, we have to isolate projects from the mainline and decouple them from one another because:

We don't really know how long it will take to completely code each new feature or behavior. By decoupling the work on them, we can release new software as soon as any of them are done instead of having to wait until they're all done.
Interim changes made in the course of development can break software. By decoupling projects we can limit the breakage so that it impacts individuals or small coding teams instead of our entire development staff.
Decoupling projects lets us test to see what we've broken without having to worry about whether the breakage is related to features and behaviors introduced by concurrent projects.
We need the mainline to remain stable so that it can serve as a reference point of quality and compatibility for all new features and behaviors.

What goes on in a development codeline depends on the nature of the project. Unlike release codelines, development codelines can be veins of significant change. Component rearchitecture, code refactoring, file restructuring—all of these things are likely to happen in a development codeline.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Creating A Development Codeline

Inhaltsvorschau

We don't really know how long it will take to completely code each new feature or behavior. By decoupling the work on them, we can release new software as soon as any of them are done instead of having to wait until they're all done.
Interim changes made in the course of development can break software. By decoupling projects we can limit the breakage so that it impacts individuals or small coding teams instead of our entire development staff.
Decoupling projects lets us test to see what we've broken without having to worry about whether the breakage is related to features and behaviors introduced by concurrent projects.
We need the mainline to remain stable so that it can serve as a reference point of quality and compatibility for all new features and behaviors.

Development codelines are continually updated from the mainline. The mainline, in turn, receives completed work from other development codelines, and that work may have been significant. Thus, change flowing into a development codeline can also bring with it rearchitecture, refactoring, and restructuring. Does this result in total chaos? No, not as long as:

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Working in a Development Codeline

Inhaltsvorschau

Once files have been branched into a development codeline, developers can begin to work in the codeline. Let's take a look at aspects of working in a development codeline that are of interest to developers.

Developers should set up separate workspaces for each development codeline in which they work. (If you're both curator and developer for the codeline, make sure

Figure 10-2: The AGUI codeline in the depot

you have a separate workspace for your own development work. It's easier to do routine codeline maintenance when you don't have to worry about interfering with your own development work in progress.)

Bob, for example, has a workspace set up for working in AGUI. It's called AGUI-bob and it's rooted in the /usr/team/bob/ws directory on his workstation. He creates it using the AGUI-master workspace as a template:


p4 client -t AGUI-master AGUI-bob

 

Client          AGUI-bob

Root            /usr/team/bob/ws

View            //Ace/AGUI/...         //AGUI-bob/...

                //Ace/MAIN/utils/...   //AGUI-bob/utils/...

Once his workspace is configured, he can fill it with AGUI files by running:


p4 sync

Often there are depot files you don't want copied to your workspace, or workspace files you don't want added to the depot. You can use your workspace view to filter these files out of the scope of Perforce commands.

If you're a Vim user, for example, your workspace may be littered with Vim backup and swap files; these files have names that end in ~ and .swp. You can hide them from Perforce with exclusion lines in your workspace view. Bob has done this by adding two exclusion lines to his AGUI-bob workspace view:


p4 client

 

Client          AGUI-bob

View            //Ace/MAIN/...   //AGUI-bob/...

                -//Ace/...~       //AGUI-bob/...~

                -//Ace/....swp    //AGUI-bob/....swp

(The exclusion lines are the ones that begin with -.) With this exclusionary mapping in effect, Perforce client programs will ignore files whose names end with ~ and .swp. When Bob uses the add command, for example, Perforce won't open these files to be added to the depot.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Keeping a Development Codeline Up to Date

Inhaltsvorschau

As you read in Chapter 7, a development codeline is a surrogate for the codeline from which it was branched. It serves its purpose best when it's up to date—that is, when all of its parent's changes have been integrated into it.

Ann, as curator of the AGUI codeline, is in charge of keeping AGUI up to date with the MAIN codeline.

There is no Perforce mechanism that keeps codelines up to date automatically. Someone has to integrate parent codeline changes into the development codeline. Typically, that someone is you, the development codeline curator. You should plan to integrate changes regularly—the more current your development codeline is, the easier it will be to integrate into the parent when the project is done.

Remember that the mainline is, in theory, stable. Because changes go into the mainline only when they're complete and working, you should have no qualms about pulling them into your development codeline.

Change should flow continually to a development codeline from its parent. That is, as soon as a change occurs in the parent, the development codeline should be ready to accept it. This means you should be integrating parent codeline changes into the development codeline as they occur. (see Figure 10-3.)

And here's why: For smoother collaboration, you'll want to make sure that your project work isn't delivered to the parent until you've solved all the integration problems it may have caused. (Integration problems are those having to do with interfaces, compatilibity, refactoring, rearchitecting, and so on.) Integration problems should be worked out in the development codeline, not in its parent codeline.

Figure 10-3: Updating the AGUI codeline

As a rule of thumb, integration problems between two codelines should be worked out in the softer of the two codelines. (See Chapter 7.) Working out integration problems always causes a bit of instability; the softer codeline can accommodate instability better than the firmer one can.

As you can imagine, the sooner you integrate parent changes to the development codeline, the sooner you and your development team will be able to flush out looming integration problems. Deferring the integration until more changes pile up only makes the problems harder to solve.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Working with Third-Party Software

Inhaltsvorschau

Third-party software is the software that comes from other suppliers and is used in source or binary form to build your software. If you're wondering whether you should check in third-party code, ask yourself, "Are we going to modify it?" If the answer is yes, you should check it in. The vendor's source will be the common base for changes you'll make; it needs to be in your depot. (You'll see an example in a moment.)

There are other reasons to put third-party software in your depot:

Most vendors distribute multiple versions or frequent upgrades of software. If you submit their distributions into your depot you'll always know which versions of their software goes with which versions of yours.
You may want control over the versions your developers use. Rather than leaving it up to developers to figure out which versions to download and when, use your depot to present the correct version to codelines and workspaces.
The Perforce depot is often the easiest place for you to store files. You don't have to get root access or set up network shares to make third-party software available to your developers. Just put it in the depot.
It may be hard or inconvenient for your developers to download from external vendors. If you put third-party software in your depot along with other files they use there's never any question about how developers are to get it.

There's a lot of switching between workspaces in the scenario described in this section. If you're not clear on how to switch between workspaces, take a look at Chapter 2.

As we hinted in Chapter 8, you should designate a depot path for storing imported, third-party code. At Ace Engineering, for example, software developed externally is imported into the //Ace/IMPORT path (a.k.a. the IMPORT stream).

You can download a supplier's distribution and add it to your depot as you would any new collection of files. For example, Ann's going to download FWindo, a toolkit she and her developers plan to use for GUI development. It's the FWindo 4.1 distribution, and it comes in a file called

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Delivering Completed Development Work

Inhaltsvorschau

Once work on a project is completed, you'll want to deliver it from the development codeline to its parent. Likewise, if a development codeline is being used for ongoing development, you'll want to deliver work to its parent at points of completion. In either case, delivery is done by using integrate, resolve, and submit to propagate new file content and new file structure to the parent codeline.

Delivering completed work is typically the job of the development codeline curator. Most of the effort is in the setup, not in the integration; the actual integration is likely to be trivial because no file merging is involved.

Delivering completed work is a matter of first bringing the development codeline up to date with the parent codeline, then copying the merged files back to the parent. In the case of the AGUI codeline, completed work will be delivered by merging MAIN into AGUI first, then copying AGUI to MAIN. (Figure 10-5.)

One advantage of this merge down, copy up approach is that when there are problems with merging, interfaces, and compatibility, the development codeline bears the brunt. The parent—the firmer codeline—remains unsullied while you sort out problems in the development codeline. Only after you've submitted fixes to the development codeline do you copy files from development codeline to parent.

Another advantage of merge down, copy up is that merging down gives you a preview of what the parent codeline will look like once you've delivered completed work

Figure 10-5: Delivering completed AGUI work to MAIN

to the parent. The development codeline is your preview—you can batter it with the same tests its parent codeline is subject to and you can show it to anyone who wants to know what you're about to deliver to the parent.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

The Soft Codelines

Inhaltsvorschau

In this section we look at the softest codelines of all: the ad hoc and private codelines used by individual developers.

As a developer you may find that from time to time you have to put work in progress aside in order to tend to a more urgent task. In Perforce there are a couple of ways to shelve work in progress so that you can pick it up again later:

As you learned in Chapter 2, one way is to simply put open files into separate pending changelists. This approach works as long as the work you're shelving doesn't interfere with the new task you're taking on. In other words, as long as you can do both things in the same workspace, with files opened for two different purposes, you're fine.
Another way to shelve work in progress is to check your files into an ad-hoc sparse branch. You create the branch expressly for the purpose of shelving your work; the only files it contains are the ones you need to shelve. Later, when you're ready to resume your work, you can run integrate to pull the shelved files back into your workspace and carry on where you left off. If this procedure sounds vaguely familiar to you it's much like what you read about it in Chapter 9, in the section called "Task Branches and Patch Branches."

Pending changelists and sparse branches are useful short-term solutions for shelving work in progress. As a developer, you may realize that there situations where it would be nice to be able to isolate your work in progress for longer intervals. You may want to submit your files before merging other peoples' changes into them, in order to reduce the risk of merging, for example. Or, you may want to submit incomplete changes to files in order to have interim versions you can roll back to. You can't do these things if you're working in a shared development branch, but you can do them in a private branch.

A private branch is a fully populated, personal codeline branched from a development codeline. The relationship of a private branch to its parent is the same as the parent's relationship to the mainline. The care and feeding of a private branch—creating it, keeping it up to date, working in it, and delivering completed development—are also the same as for a development codeline.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Chapter 11: Staging Streams and Web Content

Inhaltsvorschau

In Chapter 9 you saw how Perforce is used to keep track of software that is released two or three times a year. Web-hosted software—what we're calling web content —demands that we manage codelines in an entirely different way. For one thing, we don't have to support multiple versions. The version on our web sites is the version our customers use; we don't have to keep old versions around for patches and point-releases. But unlike shrinkwrapped software, which may be released several times a year, web content may have to be released several times a week. Given the complexity of the software that goes into a web site, we certainly don't want to be saddled with creating and managing a release codeline for each new version.

In this chapter we'll look at using staging streams to manage frequent releases. (Stream is another word for codeline. See Chapter 7) Using web content as the context, we'll see how change moves from stage to stage, how development enters the staging pipeline, and how bug fixes are treated.

Purveyors of large and rapidly evolving web sites have learned they can reduce complexity by deploying content in stages. Each stage traps problems before subsequent stages are affected. For example, the first stage might be to test whether everything can be compiled together and started up, if nothing else. The second stage might be to evaluate appearance, and the third might be to validate behavior and performance. It's certainly beyond the scope of this book to go into detail about what happens in each stage, but it's well within the scope of Perforce to manage the staging.

The key to effective staging is to stop worrying about individual files. It's just not feasible to try and mix and match files to produce a working web site when the site is large and complex. Instead we treat web content development as a sequence of web site versions. We track each version as it moves through the staging pipeline and publish live web sites from the versions that make it all the way through. This process is what we'll focus on in this chapter.

But really, this chapter is not about web content—it's about managing the Perforce codelines in which web content evolves. In fact, it's about how to manage codelines for any kind of content staging. You'll find it useful reading even if you aren't developing web content.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Staging Web Content

Inhaltsvorschau

With Perforce, we can manage deployment stages with staging streams. The strategy, in a nutshell, is this:

Each staging stream has its own path in the depot.
Each stream has its own firmness on the tofu scale. (See Chapter 7)
Web content versions are shunted from stage to stage in the soft-to-firm direction.
Jobs or labels are used to mark web content versions that are ready to move to the next stage.
Content is previewed on web sites built from staging streams.
Automated scripts do the moving when the conditions are right.
Integration history provides an audit trail of content in the staging pipeline.

To demonstrate the use of staging streams we'll look again at Ace Engineering. As with all effective demonstrations, this one is simplified so that explanations and diagrams don't overpower the concepts it is intended to illustrate. However, it involves—we hope—enough real-world conditions that you can easily construe an implementation to match more complex requirements.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Visual Content Development

Inhaltsvorschau

In order for web content to enter the staging pipeline, it must be ready to release. Scripts and other executable content, for example, have to be working correctly. Visual content has to be contextually appropriate and aesthetically pleasing. What this means is that developers need a place to check in their changes that is softer than WEBMAIN. They need a place where they can submit and preview their work in progress in order to know if it's worthy of release.

At Ace Engineering, there are two codelines where developers may submit their work in progress, WEBENG and WEBVIS . (See Figure 11-4.) Both are branched from WEBMAIN.

Figure 11-4: Web development codelines

WEBENG and WEBVIS are both used for ongoing web development, and both are soft enough for developers to make refinements before their work is released. Having two development codelines instead of one separates executable content development from visual content development. The two content types are separated because each has its own flow of change:

Executable web content consists primarily of scripts and programs. The flow of change we explored in Chapter 10 works very well for developing executable web content . As a matter of fact, Pam manages the WEBENG codeline very much the same way Ann manages the AGUI codeline: The WEBENG codeline, in which both app and www are active modules, is kept up to date with WEBMAIN. At points of completion, work is delivered from WEBENG to WEBMAIN.
Visual web content Ace's is a different animal entirely. For one thing, developers tend to work piecemeal and independently. For another, the files they work on are difficult or impossible to merge. The merge down, copy up protocol simply doesn't apply to this kind of development.

In this section we'll focus on shepherding visual web content from development to release.

The WEBVIS codeline is dedicated to visual content development. Eric, the lead web designer, is in charge of it. Of the two top-level modules in WEBMAIN, only www is branched to WEBVIS. (The app module contains nothing that needs to be on local disk to work on visual content.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Bug Fixes and Staging Streams

Inhaltsvorschau

So, what happens if a bug is found in testing? Or worse, if a bug is found in the published release? The answer depends on the severity of the bug, what it takes to fix it, and the state of current development. We'll see how these play out in three different scenarios.

Many non critical bugs are found during the release cycle and after a release is published. They are not fixed in the staging streams, however. They're fixed in a development codeline, either WEBVIS or WEBENG. Non-critical bug fixes enter WEBMAIN and migrate through WEBQA to WEBLIVE according to the normal release cycle.

This is quite different, you'll notice, than how we treat release codelines. We branch release codelines specifically to fix bugs. We have time in the schedule to rerun tests as we make changes in release codelines; this assures that our bug fixes haven't broken anything else.

But with extremely frequent releases we have to keep content moving through the cycle. If we were to make changes in WEBQA, we'd have to retest the code in WEBQA. And if were to retest the code in WEBQA, we'd have to delay testing the next release from WEBMAIN. Since it takes only a day or so to get WEBMAIN fixes into WEBLIVE in any case, we're better off keeping releases moving than holding them up for noncritical bugs .

Now let's consider what happens when testing uncovers a show stopper bug in the WEBQA stage. Remember, the WEBQA stream was copied from a recent version of WEBMAIN. The first thing to do is to check the http://webmain.ace.vis site for evidence of the bug—or lack of it—in WEBMAIN. If we're lucky, the bug will have already been found, fixed, and released to WEBMAIN. In this case all we have to do is abort testing in WEBQA and restart it with a new version pulled in from WEBMAIN.

If the bug is not fixed in WEBMAIN we have a choice. We can fix it in WEBQA or we can fix it in a development codeline—either WEBVIS or WEBENG. Fixing it in a development codeline is easiest because it's how developers normally work. It does mean, however, that the version currently in WEBQA will have to be abandoned. We'll have to wait until the next WEBMAIN version is ready before we can start testing again. as shown in(Figure 11-10.)

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Major Web Development

Inhaltsvorschau

The staging streams and development codelines described in the previous examples are suitable for ongoing, iterative web content development. They don't really work for major web development projects . If we have a new development project afoot—a project that will take several months to complete, for example—we're going to have to isolate it to keep it from disrupting ongoing development. On the other hand, we don't want the project living under a rock, either—we need a way to get it into the QA cycle and onto beta test sites well in advance of introducing it into our production web content pipeline.

Our solution is to set up a parallel pipeline, as shown in the example in Figure 11-11. The Perforce commands for creating and using a parallel pipeline have already been covered, in this chapter and in previous chapters. Instead of demonstrating with examples here, let's just take a look at the big picture.

Figure 11-11: Parallel pipeline for major new development

To launch our major new development project, we branched WEBMAIN into a development codeline called BETAMAIN . BETAMAIN is a shared development codeline; our developers will use it for the new project. As bug fixes and minor enhancements flow into WEBMAIN, they are merged into BETAMAIN. However, until the project is complete, no change will flow from BETAMAIN to WEBMAIN. This assures that content leading to the WEBLIVE steam remains undisturbed by the groundbreaking changes in BETAMAIN.

Meanwhile, we've branched BETAMAIN into a staging stream called BETAQA. BETAQA serves the same purpose as WEBQA—it's used to subject web content to testing. Change flows between BETAMAIN and BETAQA as the project evolves. The test cycle in BETAQA is necessarily irregular—even infrequent at first—but as the project matures, tests become more extensive and the cycle becomes more frequent. All the while change is flowing from WEBMAIN into BETAMAIN, keeping BETAMAIN completely up to date with our current web content.

Eventually, when BETAMAIN matures to a point that it's ready to see the light of day, we branch BETAQA into BETALIVE. External beta web sites are built from BETALIVE, selected customers come to the beta web sites, and bugs are reported. Bugs are fixed in BETAMAIN; they flow through BETAQA to BETALIVE. The flow of change from BETAMAIN to BETALIVE now matches the flow of change from WEBMAIN to WEBLIVE. This parallel pipeline allows us to stabilize the development project without affecting our production web sites.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Appendix A: Setting Up a Perforce Test Environment

Inhaltsvorschau

This book is not a tutorial—there are no exercises to follow, no drills to complete, and no working sample programs to run. But if your interest is piqued as you read along, you may want to try a few things yourself. You'll be happy to know that it takes about 10 minutes to set up a Perforce test environment, complete with server.

There are caveats, however:

Although You don't need a Perforce license to run a Perforce Server, an unlicensed server will support only two users and five workspaces.
The quick setup steps described here are no substitute for a well-informed Perforce installation procedure. If you want to set up a Perforce Server for production use, please follow the instructions in the The Perforce System Administrator's Guide.
Perforce installation procedures vary slightly from release to release. The procedures described here are based on Perforce Release 2005.1.

Section A.1: Setup

Section A.2: Connecting to Other Servers

Section A.3: Getting Help

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Setup

Inhaltsvorschau

You should plan to download and install, at a minimum, P4, the Perforce Command-Line Client, and P4D, the Perforce Server. You should also install P4V, the Perforce Visual Client, and P4Web, the Perforce Web Client, as both come up occasionally in examples in this book.

You can run the Perforce Server on the same machine you'll be using to run your client programs. Or, if you prefer, you can use the client programs on one machine while running the server on another. In either case, make sure you download and install the software matches the machines on which you plan to run it.

Perforce offers two graphical clients for Windows, P4V and P4Win. P4V is newer and is available for non-Windows platforms as well as for Windows. As of Release 2005.1, P4V comes bundled in Perforce's core product installer for Windows. (The core installer also includes P4, P4D, and P4Web.)

P4Win is Peforce's classic Windows client. It can be downloaded separately in its own installer.

There are also two graphical merge tools available on Windows. The newer one is P4Merge; it's available both as a stand-alone program and as an embedded feature of P4V. P4Merge comes with the core installer. The classic merge tool for Windows, P4WinMerge, comes with the P4Win installer.

You don't have to be a Windows administrator to install Perforce for your own use. However, the steps that follow match the Perforce installer's behavior when are an administrator. If you're not an administrator you'll see different dialogs and defaults, and programs that are normally installed as services will be installed as command executables.

Go to www.perforce.com and follow the Download links to the Windows page. Download the core installer for Windows and run it. In the first configuration dialog, select Administrator → Typical. Now follow the dialogs to the end, accepting the default values.
In a Command Prompt window, run these commands to create your Perforce workspace:
```
mkdir c:\p4workspace

pushd c:\p4workspace

p4 set P4CLIENT=testws

p4 client -o | p4 client -i
```
This sets up a Perforce workspace called

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Connecting to Other Servers

Inhaltsvorschau

Your Perforce environment is set up to connect you to your test server. Once you've downloaded and installed the Perforce client programs, however, you can use them to access any Perforce Server available to you.

First, find out the address of the Perforce Server you'd like to connect to. The address will be of the form hostname:port, where hostname is the network-visible name (or the IP address) of the machine on which the server is running, and port is a TCP/IP port number.

One Perforce Server that is available to everyone is the Perforce Public Depot. Its address is public.perforce.com:1666.

You can configure your Perforce Server address by setting P4PORT:

On Unix and Mac OS X, you can set P4PORT as an environment variable. For example:
```
export P4PORT=public.perforce.com:1666
```
On Windows, you can use P4 to set P4PORT in the Windows registry:
```
p4 set P4PORT=public.perforce.com:1666
```

Both P4 and P4Web will respect your environment's P4PORT setting. The P4Web daemon, however, will have to be stopped and restarted after P4PORT is changed.

P4V, on the other hand, keeps its own registry of server addresses. It remembers the ones you've connected to, and other than the first time you start it up, it won't refer to your machine's P4PORT setting at all. To change to a different server, use P4V's Connection → Open Connection dialog.

The Perforce Server you're connected to tells you a little about itself when you run P4's info command:


p4 info

Server address: public.perforce.com:1666

Server root: /usr/depot/public

Server date: 2005/07/31 09:58:21 -0700 PDT

Server version: P4D/FREEBSD4/2005.1/80277 (2005/05/25)

Server license: Perforce Public Depot 1000 users (expires 2007/07/31)

P4V and P4Web display your Perforce Server address in the top of the main window or page.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Getting Help

Inhaltsvorschau

While you're learning about Perforce you can get help from any of these sources:

The Perforce manuals online at http://www.perforce.com/perforce/technical.html.
The Help button in any of the Perforce graphical interfaces (P4V, P4Win, and P4Web).
The P4 help command:
```
p4 help
```
The Perforce user discussion list and email archive at http://maillist.perforce.com/mailman/listinfo/perforce-user.
The Perforce Software technical support staff at support@perforce.com.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Appendix B: Perforce Terminology and P4 Commands

Inhaltsvorschau

Perforce has been a player in the software development world for 10 years now. Its first user interface was P4 , the Perforce Command-Line Client. To this day, P4 remains the canonical interface to the Perforce Server. Some P4 command terminology is anchored deep in the server and dates back to the earliest versions of Perforce. Some has been updated to reflect new environments and tools with which Perforce is used. The total effect is not always consistent; Perforce terminology and P4 commands are, admittedly, a bit confusing.

This appendix explains the terms that seem to be the most confusing, and within each explanation, lists the P4 commands that are related to them.

"Submit" and "check in "

In Perforce, submit and check in mean the same thing. We usually say submit because the P4 submit command checks files in to the repository.

"Changelist" and "change"

A changelist , in Perforce, is a collection of files submitted together. In the earliest versions of Perforce, the term changelist didn't exist. The concept did exist, however, and its corresponding database object was called a change. When that proved difficult to document in clear English, the term changelist was introduced, although the early terminology persists in the Perforce Server. In this book, change and changelist are often used interchangeably.

The P4 change command doesn't change files. It allows you to define a changelist.
The submit command submits a changelist.
The changes command shows pending and submitted changelists .
The changelist and changelists commands are aliases for change and changes.
The filelog command shows when files were changed, and by whom.
The P4 commands that show how files have changed are annotate, diff, and diff2.

"Client" and "workspace"

Perforce workspaces were originally called clients . By popular demand, that terminology is changing; Perforce tools and documentation now refer to

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Appendix : Bibliography

Inhaltsvorschau

"Pragmatic Software Configuration Management," by Steve Berczuk. In IEEE Software Magazine, March/April 2003. http://www.berczuk.com/pubs/IEEESW_2003-03.pdf

"Patterns and Software Configuration Management," by Steve Berczuk, Steve Konieczka, and Brad Appleton. In Crossroads News, April 2004. http://www.cmcrossroads.com/newsletter/articles/agileapr04.pdf

"Streamed Lines: Branching Patterns for Parallel Software Development," by Brad Appleton, Stephen Berczuk, Ralph Cabrera, and Robert Orenstein. I n PLoP '98 Conference Proceedings. http://www.cmcrossroads.com/bradapp/acme/branching/

"To Use or Be Reused; Techniques for Component Composition and Construction," by Merijn de Jonge. http://www.cs.uu.nl/~mdejonge/papers/ToReuseOrToBeReused.pdf. Also "Package-based Software Development," by the same author.

"Web Content Management; A Collaborative Approach," by Russell Nakano. Reading, MA: Addison-Wesley, 2002

"Codeline Merging and Locking: Continuous Updates and Two-Phased Commits," by Brad Appleton, Steve Konieczka, and Steve Berczuk. In Crossroads News, November 2003. http://www.cmcrossroads.com/articles/agilenov03.pdf

"Merging Defect Fixes into the Development Codeline," by Michael Sayko. In Crossroads News, November 2003. http://www.cmcrossroads.com/articles/msnov03.pdf

"Parallel Development Strategies for Software Configuration Management," by Tom Bret. In Methods & Tools, summer 2004.

"ABCs of a Branching and Merging Strategy," Mario Moreira, Crossroads News, November 2003, www.cmcrossroads.com/newsletter/articles/mmnov03.pdf

"Pragmatic Version Control Using CVS," by David Thomas and Andrew Hunt. In The Pragmatic Bookshelf, 2004.

"The Online Jargon File v 4.4.7," by RetroLogic Systems, 2005. http://www.retrologic.com/jargon-file.html

"Inter-File Branching: A Practical Method for Representing Variants," by Christopher Seiwald. Sixth International Workshop on Software Configuration Management (I-SCM6), Berlin, Germany, March 1996; in Software Configuration Management: Selected Papers of the ICSE SCM-6 Workshop, edited by Ian Somerville. City: Springer-Verlag, 1996, pp. 67–75.

Ende der Inhaltsvorschau. Der weiterere Inhalt dieses Abschnitts ist hier nicht einsehbar.

Zurück zu Practical Perforce

Inhaltsverzeichnis

Themen

Buchreihen

Special Interest

International Sites