book

Practical Perforce

Name: Practical Perforce
Author: Laura Wingerd
ISBN: 9780596518073

by Laura Wingerd

November 2005

Intermediate to advanced

256 pages

9h 12m

English

O'Reilly Media, Inc.

Read now

Unlock full access

Preface
What Is Perforce?The Perforce System in a NutshellWhy Perforce?About This BookWhat’s Not In This BookAdditional ReadingConventions Used in This BookUsing Code ExamplesSafari® EnabledHow to Contact UsAcknowledgements
1. Files in the Depot
1.1. The Perforce Filespec Syntax1.1.1. The depot hierarchy1.1.2. Wildcards and file collections1.1.3. Views and mappings1.1.4. File and directory revisions1.1.5. Changes and changelists1.2. Browsing Depot Files1.2.1. Navigating the file tree1.2.2. Listing directories1.2.3. Listing directory history1.2.4. What’s in a changelist?1.2.5. Listing files and file information1.2.6. Finding files1.2.7. Perusing file history and file origins1.2.8. Perusing file content1.2.9. Saving informal copies of files1.2.10. Comparing depot files1.2.11. Comparing depot directories1.3. File Types at a Glance1.3.1. Type modifiers1.3.2. What kind of file is this?
2. Working with Files
2.1. An Overview2.2. Creating A Workspace2.2.1. Specs and spec forms2.2.2. Editing a client spec2.2.3. Customizing a Workspace View2.2.4. Identifying the current workspace2.2.5. Listing Workspaces2.2.6. Setting the current workspace2.2.7. Switching between workspaces2.3. Synchronizing a Workspace2.3.1. Listing unsynchronized files2.3.2. Synchronizing the entire workspace2.3.3. Synchronizing in bits and pieces2.3.4. When did I last synchronize?2.3.5. What’s new in the depot?2.3.6. Synchronizing with older revisions2.3.7. Listing files in your workspace2.3.8. Detecting missing workspace files2.3.9. Replacing missing files2.3.10. Detecting files that didn’t come from the depot2.4. Local Syntax, Wildcard Expansion, and Special Characters2.5. Working with Local Files2.5.1. Opening files for editing2.5.2. Which files am I working on?2.5.3. Who’s working on these files?2.5.4. Which files did I change?2.5.5. Adding new files to the depot2.5.6. Adding an entire directory tree of files2.5.7. Deleting depot files2.5.8. Cloning depot files and directories2.5.9. Modifying files as you clone them2.5.10. Renaming files and directories2.5.11. Replacing and swapping file content2.5.12. Locking files2.5.13. Designating file types2.5.14. Changing the type of existing files2.5.15. Opening files after the fact2.5.16. Reverting files2.6. Working with Pending Changelists and Submitting Files2.6.1. Submitting a pending changelist2.6.2. Preventing unchanged files from being submitted2.6.3. Creating additional changelists2.6.4. Do I have more than One pending changelist?2.6.5. Moving files from one changelist to another2.6.6. What’s in this changelist?2.6.7. Submitting a numbered pending changelist2.6.8. Getting rid of empty changelists2.6.9. Submitting a Subset of opened files2.6.10. When submit fails2.6.11. Resolving files2.6.12. Listing unresolved files2.7. Removing and Restoring Files2.7.1. Removing workspace files2.7.2. Deleting depot files2.7.3. Obliterating files2.8. Useful Recipes2.8.1. Reconciling offline changes2.8.2. Backing out a recent change
3. Resolving and Merging Files
3.1. Resolving: When, What, and How3.1.1. Are You in Sync?3.1.2. Which files need resolving?3.1.3. Resolving files automatically3.1.4. “Yours,” “theirs,” and “base”3.1.5. Resolving files by copying theirs into yours3.1.6. Resolving files by ignoring theirs3.1.7. Resolving files by merging theirs into yours3.1.8. Resolving files interactively3.1.9. Perforce doesn’t merge binary files3.1.10. What’s been resolved, and how?3.2. How Perforce Merges Text Files3.2.1. Chunks and conflicts3.2.2. A simple file merge3.2.3. Merging moved lines3.2.4. Comparing whitespace3.3. Reconciling Structural Changes3.3.1. Someone adds the files you were going to add3.3.2. Someone deletes the files you were going to delete3.3.3. Someone renames the files you were editing3.3.4. Someone moves the files you were editing3.3.5. Someone combines the files you were editing with other files3.3.6. Someone deletes the files you were editing3.3.7. Someone edits the files you were going to delete3.3.8. Someone edits the files you planned to rename or move3.3.9. Reconciling file type changes3.4. Tips for Smoother Collaboration3.4.1. Keep your workspace synchronized3.4.2. Synchronize and resolve one changelist at a time3.4.3. Be on the lookout for changes that can’t be resolved3.4.4. Submit logical changelists3.4.5. Check your merged files3.5. The Arcana of Merging3.5.1. Forced merging3.5.2. Can you undo or redo a resolve?3.5.3. Can you undo a merge?3.5.4. What happens when you revert files?3.5.5. Backing out changes, revisited3.5.6. Configuring P4 to use P4Merge3.5.7. Configuring an alternate merge tool3.5.8. Merging nontext files3.5.9. Setting P4MERGE
4. Branching and Integration
4.1. The Classic Case for A Branch4.2. Creating Branches4.2.1. Opening files for branching4.2.2. Branching from a point in time4.2.3. Am I branching the right files?4.2.4. Oops, I branched the wrong files!4.2.5. It’s not a branch until the files are submitted4.2.6. Can you undo and redo a branch?4.2.7. Creating really huge branches4.2.8. Working in a New Branch4.2.9. Browsing branch history4.2.10. Comparing branches4.3. Integrating Changes from Branch to Branch4.3.1. Which Changes Need Integrating?4.3.2. Integrating Changes incrementally4.3.3. Integrations won’t be repeated4.3.4. Which files need resolving ? (And why?)4.3.5. “Yours”, “theirs”, and “base”, revisited4.3.6. Merging the donor file into the target4.3.7. Copying the donor file into the target4.3.8. Ignoring the donor file’s changes4.3.9. Editing files as you’re integrating them4.3.10. Integrating by subdirectory4.3.11. Cherry-picking changes to integrate4.3.12. Integrating all changes at once4.3.13. Which Changes Were Integrated?4.3.14. Don’t break up changelists4.4. Reconciling Structural Changes4.4.1. Using branch views4.4.2. Looking for a branch view4.4.3. Branch views are reversible4.4.4. Mapping one directory structure to another4.4.5. Keeping added files from being propagated4.4.6. Keeping target files from being deleted4.4.7. Preventing warnings about deleted target files4.5. The Arcana of Integration4.5.1. Reconciling Split and Combined Files4.5.2. Integration history can’t be undone4.5.3. Forcing Perforce to Redo an Integration4.5.4. The mechanics of integration4.5.5. What interchanges really tells us4.5.6. Decoding integration history4.5.7. Why does editing matter?4.5.8. The curious syntax of the integrate command
5. Labels and Jobs
5.1. Saving Important Configurations5.1.1. Changelists and dates: the automatic snapshots5.1.2. Comparing snapshots5.2. Using Labels5.2.1. Applying a label to files5.2.2. Referring to labels5.2.3. Which files did I label?5.2.4. Locking a label5.2.5. Do you really need a label?5.2.6. Labeling the current workspace configuration5.2.7. What’s the difference between tag and labelsync?5.2.8. Finding and comparing labels5.2.9. Reusable labels (rolling labels)5.2.10. Archiving rolling labels with unique labels5.2.11. Archiving rolling labels in files5.2.12. Labels have views , too5.2.13. Removing a label5.2.14. Labels, snapshots, and workspaces5.3. Using Jobs5.3.1. What is a job?5.3.2. Creating jobs5.3.3. Searching for jobs5.3.4. Linking jobs to changelists5.3.5. Preselecting your own jobs5.3.6. Linking jobs to changelists after the fact5.3.7. Searching for job fixes5.3.8. Deleting and restoring jobs5.3.9. Jobs can’t be locked5.4. Jobs as Changelist Markers5.4.1. Marking changelist numbers5.4.2. Looking up changelist numbers by job
6. Controlling and Automating Activity
6.1. Depot and File Access6.1.1. Creating a new depot6.1.2. Depot protections6.1.3. Groups6.2. Accessing Files in Other Domains6.2.1. Switching domains6.2.2. How remote depots work6.2.3. Distributed software...6.2.4. ...versus distributed software development6.3. Saving and Restoring Specs6.3.1. Setting up a spec depot6.3.2. Restoring a spec6.4. Change Notification and Change Monitoring6.4.1. The Perforce change review daemon6.4.2. Subscribing as a depot path reviewer6.4.3. Review daemon commands6.4.4. Using P4Web and browser bookmarks to monitor changes6.4.5. Hyperlinks to Perforce files and objects6.4.6. Undocumented P4Web URL tricks6.5. Scripting Tips6.5.1. The fstat command6.5.2. Tagged output6.5.3. Marshalled output6.5.4. Dates and times6.5.5. Specs and spec forms6.5.6. Scripting language extensions6.5.7. Don’t swamp your server6.5.8. Triggers6.6. Behind-the-Scenes Version Control6.6.1. WebKeeper, a Perforce module for Apache6.6.2. P4Web, Perforce’s own web server6.6.3. How are WebKeeper and P4Web different?6.6.4. Perforce via FTP6.6.5. Windows applications and perforce plug-ins6.6.6. Perforce as ODBC data source
7. How Software Evolves
7.1. The Story of Ace Engineering7.2. The Mainline Model7.2.1. From ideal world to real world7.2.2. The flow of change7.2.3. Branching from release codelines7.2.4. Branching from development codelines7.2.5. Soft, medium, and firm: the tofu scale7.2.6. A codeline by any other name...7.2.7. One-way codelines7.2.8. Codelines that aren’t codelines7.2.9. Musings on codeline diagrams7.3. Ace Engineering Revisited7.4. Containerizing7.4.1. Modules7.4.2. Codelines7.4.3. Bodies of Code
8. Basic Codeline Management
8.1. Organizing Your Depot8.1.1. Filespecs as containers8.1.2. The depot hierarchy8.1.3. The scope of a depot8.1.4. Codeline grouping8.1.5. Lineage versus location8.1.6. Depot path naming conventions8.1.7. Storing generated files8.1.8. Codeline proliferation8.1.9. How not to organize your depot8.2. General Care and Feeding of Codelines8.2.1. The codeline curator8.2.2. Naming a codeline8.2.3. Which modules go in a codeline?8.2.4. The master workspace8.2.5. The codeline’s branch view8.2.6. Branching a codeline8.2.7. Working in a codeline8.2.8. Controlling access to a codeline8.2.9. Retiring a codeline8.3. Nightly Builds8.3.1. The nightly build workspace8.3.2. Synchronizing the nightly build8.3.3. Opening generated files8.3.4. Submitting generated files8.3.5. Labeling nightly builds8.3.6. Using the nightly build label8.4. Is Bug X Fixed in Codeline Y?8.4.1. Inside the perforce database8.4.2. Commands that detect merged bug fixes8.4.3. False positives8.4.4. Making merge detection more accurate
9. Release Codelines
9.1. Creating a Release Codeline9.1.1. When should we branch?9.1.2. Who owns the release codeline?9.1.3. Naming a release codeline9.1.4. Which modules should we branch?9.1.5. A branch view for the release codeline9.1.6. The master workspace9.1.7. Are we branching the right files?9.1.8. A label view for the branch point9.1.9. Labeling the branch point9.1.10. Creating the release codeline—really!9.1.11. Branching more files later9.2. Working in a Release Codeline9.2.1. The developer’s workspace9.2.2. What to document in the change descriptions9.2.3. Fixing a bug? Fix a job!9.2.4. What if i can’t check in a change?9.2.5. Keeping the branch view up to date9.3. Integrating Changes into the Mainline9.3.1. Which changes should be integrated?9.3.2. When should changes be integrated?9.3.3. Who does the integration?9.3.4. A workspace for integrating into MAIN9.3.5. Finding unintegrated changes9.3.6. When it’s okay to integrate changes out of order9.3.7. Integrating a change9.3.8. How much has the mainline changed?9.4. Making a Release9.4.1. Building the release9.4.2. Labeling the release9.4.3. Making point releases9.4.4. Generating release note information9.5. Distributing Releases9.5.1. From release codeline to distribution stream9.5.2. From distribution stream to FTP site9.5.3. Oops, we released the wrong build!9.5.4. Using P4FTP as a sync daemon9.6. Breaking the Rules9.6.1. Backporting a bug fix9.6.2. Pulling late-breaking development into a release9.7. Retiring a Release Codeline9.7.1. Who’s still working in a release codeline?9.7.2. Are all changes integrated?9.7.3. Setting protections to prevent changes9.7.4. Setting protections to hide a retired codeline9.7.5. Annotating a release codeline’s branch and label views9.8. Task Branches and Patch Branches9.8.1. Creating a task branch9.8.2. Working on files in a task branch9.8.3. Keeping a task branch and its workspace up to date9.8.4. Reviewing and integrating task branch changes9.8.5. Creating a patch branch

10. Development Codelines
10.1. Creating A Development Codeline10.1.1. Why a Development Codeline?10.1.2. What goes on in a development codeline?10.1.3. Who owns the development codeline?10.1.4. Naming the development codeline10.1.5. Which modules should we branch?10.1.6. Why branch static modules ?10.1.7. A branch view for the development codeline10.1.8. Creating a master workspace10.1.9. Branching the development codeline10.2. Working in a Development Codeline10.2.1. The developer’s workspace10.2.2. Workspace File Filters10.2.3. Writing helpful changelist descriptions10.3. Keeping a Development Codeline Up to Date10.3.1. When should a development codeline be updated?10.3.2. Which changes need integrating?10.3.3. Adjusting the development codeline’s branch view10.3.4. Integrating changes10.4. Working with Third-Party Software10.4.1. Importing third-Party software10.4.2. Branching imported code to the development codeline10.4.3. Updating the development codeline’s branch view10.4.4. Importing a new distribution10.4.5. Merging a new distribution with local changes10.5. Delivering Completed Development Work10.5.1. Merge down, copy up10.5.2. When should development be delivered?10.5.3. Identifying a Point of Completion10.5.4. Which changes should be integrated into the parent?10.5.5. Freezing the parent codeline10.5.6. Which Workspace?10.5.7. Preparing a change description10.5.8. Normalizing the branch view10.5.9. Integrating into the parent codeline10.5.10. Integrating neglected files10.5.11. Thawing the parent codeline10.5.12. Retiring a development codeline10.6. The Soft Codelines10.6.1. Shelving Work in Progress10.6.2. Private branches10.6.3. Code reviews10.6.4. Reparenting a private branch10.6.5. Redeploying a private branch
11. Staging Streams and Web Content
11.1. Staging Web Content11.1.1. Web Content at Ace Engineering11.1.2. The Release Cycle11.1.3. How Web Sites Are Updated11.1.4. Pulling a release into testing11.1.5. Publishing a tested release11.1.6. Release timing is flexible11.1.7. The web content audit trail11.2. Visual Content Development11.2.1. The visual content codeline11.2.2. Working on visual content11.2.3. What’s ready to be released?11.2.4. Automating continuous integration11.2.5. Enforcing the use of jobs11.2.6. Preventing merging11.3. Bug Fixes and Staging Streams11.3.1. Non critical bugs11.3.2. Show stoppers in WEBQA11.3.3. Rolling back the published web site11.3.4. Forcing integration after a roll-back11.4. Major Web Development
A. Setting Up a Perforce Test Environment
A.1. SetupA.1.1. Installing Perforce on WindowsA.1.2. Installing Perforce on Linux and other Unix systemsA.1.3. Installing Perforce on Mac OS XA.1.4. Your test environmentA.2. Connecting to Other ServersA.2.1. Which server am I connected to?A.3. Getting Help
B. Perforce Terminology and P4 Commands
C. Bibliography
Glossary
About the Author
About the Author
Colophon
Copyright

Content preview from Practical Perforce

Chapter 9. Release Codelines

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.)

Creating a Release Codeline

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.

When should we branch?

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 ...

Become an O’Reilly member and get unlimited access to this title plus top books and audiobooks from O’Reilly and nearly 200 top publishers, thousands of courses curated by job role, 150+ live events each month,
and much more.

Read now

Unlock full access

More than 5,000 organizations count on O’Reilly

O’Reilly covers everything we've got, with content to help us build a world-class technology community, upgrade the capabilities and competencies of our teams, and improve overall team performance as well as their engagement.

Julian F.

Head of Cybersecurity

I wanted to learn C and C++, but it didn't click for me until I picked up an O'Reilly book. When I went on the O’Reilly platform, I was astonished to find all the books there, plus live events and sandboxes so you could play around with the technology.

Addison B.

Field Engineer

I’ve been on the O’Reilly platform for more than eight years. I use a couple of learning platforms, but I'm on O'Reilly more than anybody else. When you're there, you start learning. I'm never disappointed.

Amir M.

Data Platform Tech Lead

I'm always learning. So when I got on to O'Reilly, I was like a kid in a candy store. There are playlists. There are answers. There's on-demand training. It's worth its weight in gold, in terms of what it allows me to do.

Mark W.

Embedded Software Engineer

Publisher Resources

ISBN: 0596101856Errata

Cloud Computing

Data Engineering

Data Science

AI & ML

Programming Languages

Software Architecture

IT/Ops

Security

Design

Business

Soft Skills

Practical Perforce

by Laura Wingerd

Chapter 9. Release Codelines