The new Streams feature in Perforce 2011.1 provides an out of the box workflow that enables new members on a project to get the big picture instantly, skip any configuration details, and start working right away. Streams provide guidance for managing how changes flow from one branch or codeline to another. If you think of changes flowing between the various codelines, then streams are the channels that help you make sure each changes gets to the right places in the right way.

This is P4V on Windows, but it will look and function the same on Mac, Unix and, Linux. For this example, I'm a software developer working on a product called Jam. I want to work in the branch that holds development work for the next release, 2.3. To view Streams, I will select it from the View menu here. Let’s examine the stream graph to get oriented on this project. The connections between streams show how they are related and the hierarchy shows their relative stability. A more stable branch is closer to final release, like a release maintenance branch. A less stable branch is farther from final release, like a branch used for new development. Dev2.3 is a child of main used for new development work, so it is connected to main and shown below it in the graph. Rel2.1 is also a child of main but it is a stable release used only for bug fixes so it is shown above main on the graph. In this project, main in the parent of both the development and release streams.

The arrows show how change is supposed to flow between the streams. Dev2.3 can accept changes merged from main, and can also copy changes to main. So there are two arrows, one showing a merge and the other showing a copy. In the mainline branching model, changes are merged down to less stable branches; we accept the risk of conflicts and re-testing in the less stable branch. When a less stable branch nears a point of completion, changes are copied or promoted up to the more stable branch. A copy makes the two branches identical in content, and there is no chance of a conflict. Rel2.1 is already released, so it doesn't accept new changes from main. However, changes from Rel2.1, typically bug fixes can be merged down to main.

To start working on the 2.3 stream, I'm going to right-click on that stream and select New workspace.I'll name this workspace bruno_jam_dev23 and put it into a new directory. Notice that the stream field is already filled out, and I have the selected the option to start using this new workspace immediately. I also want to select the option to have the workspace populated immediately. Now the relevant files are on my local workstation and I'm all set to start working in this stream. I'm going to make a small change to glob.c and submit it back into the depot as would normally happen in P4V.

After completing my work on the 2.3 stream, I'm ready to promote the change to main. But I look at the stream graph and see the merge arrow from main to dev2.3 lit up. That means there are changes in main that I still need to merge. If I tried to copy my changes up before merging down, I'd get a warning message, which is why the copy arrow is red. Streams use the mainline model, and one of the principles is that changes from more stable streams, main in this case, need to be merged down into less stable streams, such as dev2.3.

I'll right-click on dev2.3 and select merge/integrate. That brings up the merge dialog. The source stream is already filled out; in streams, Perforce knows where merges to dev2.3 usually come from. Of course, you can work outside the normal merge pathways if you need to; merging a ‘hot fix’ patch is an example where the normal procedures might not be followed. The other default options look fine for now, so I'll run the merge.

The merged changes are waiting in a new changelist for me to resolve. I'm going to let Perforce automatically merge whatever it can. There were no merge conflicts, so that took care of everything. At this point I'd normally run some tests on the dev2.3 stream to make sure that everything still works correctly in my workspace. Then I'll go ahead and submit this change.

Now I'm ready to copy my completed dev2.3 work up to main. I've already accounted for any changes in main and verified that things work correctly. So I want to make the contents of main identical to the contents of dev2.3, which we call a copy operation. I'll start by context-clicking on main and choosing the copy option. P4V moved my workspace to main during this operation; I’ll come back to that a bit later.

A copy up is a simple operation, so I'll accept the default options in the copy dialog and submit automatically. The merge arrows are no longer lit up, which means that there's nothing waiting to be merged or copied between main and dev2.3. When there are new pending merges or copies, I’ll see the arrows lit up with the light green color again.

Let’s discuss workspace options now. Back in the stream graph, notice the workspace icon on main. That tells me that I'm currently working in the main stream. Normally I work in the dev2.3 stream, but once in a while I need to do a bug fix in the rel2.1 stream. There's two ways I can manage that. First, I can re-use a single workspace, and move that workspace from stream to stream. That makes sense if I have a lot of data in my workspace, and don't want to have several copies lying around. It's also convenient if I have build tools already configured for this workspace. To move a workspace in the stream graph. I'll just pick up the workspace icon and drag it to the rel2.1 stream. Behind the scenes, Perforce only updated the files in the workspace that actually differ between the two streams, so moving a workspace is usually fast. Let's go back to the dev2.3 stream.

The other way I can handle working in multiple streams is to use a different workspace for each stream. Having a separate workspace for each stream may be more convenient if you need different IDE projects or build configurations for each stream. I’ll change my P4V preference to work this way. Now as I switch streams, P4V prompts me to make a new workspace if necessary or re-use another workspace for that stream. I already had another workspace set up for main, so I can just re-use that, or make a brand new workspace. Whatever way you choose to work, P4V makes it fast and easy to work in several streams.

That wraps up our quick introduction to using Perforce streams. Streams provide an easy way to start working in a project, merge changes between codelines, and switch from task to task.

Thanks for watching!

Course - Using Streams to Simplify Codeline Management