Perforce Streams is how branching and merging is performed with Helix Core. Streams brings “built-in” intelligence to managing how changes flow from one branch or codeline to another.
Streams makes life easier for developers. One of the many benefits of Streams is an out of the box workflow that lets team members get the big picture instantly and bypass tedious configuration details so they can start working right away.
Streams provides guidance to developers in real time for managing how changes flow from one branch or code line to another. If you think of changes flowing between the code lines, Streams provides channels that help you make sure each change gets to the right place in the right way. There are many options for Streams, but in this video, we will stick to the basics.
This is the Helix Core P4V visual client running on Windows. It will look and function the same on Macintosh and Linux workstations, too. You can work with Streams very nicely from the P4 commandline, as well.
A unique feature of P4V is the Stream Graph, which shows your project’s codelines and branches, and helps you very quickly and easily see the flow of change between them.
For this example, I'm a developer working on a product called Jam. I need to work in the branch that holds development work for the next release, which is dev 2.3.
To view the Streams, I will select Streams from the view menu.
The Stream Graph lets us quickly get oriented on the project. The connections between streams show how they are related. The hierarchy shows their relative stability. A more stable branch is closer to the final release, like a release maintenance branch. A less stable branch is further from final release, like a branch you use for new development.
Dev 2.3 is a child of Main used for new development work, so it is connected to Main and shown below it in the graph. Rel 2.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 is the parent of both the development and the release streams.
The arrows between the Streams show how change normally flows between them. Dev 2.3 can accept changes merged down from main and can also copy or promote changes up to main. So, there are two arrows, one showing merge and the other showing copy. In the mainline branch model, changes are merged down to less stable branches.
We accept the risk of conflicts and retesting 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, so there's no chance of conflict. Rel2.1 is already released so it doesn't accept new changes from Main.
However, changes from rel 2.1, typically bug fixes, can be merged down to main.
To start working on the dev 2.3 Stream, I'm going to right-click on that Stream and select new workspace. I'll name this new workspace, Aruna_jam_dev_2.3, and I'll accept the default workspace root directory. Notice that the stream field is already filled out and I've also selected the option to start using this new workspace immediately. I also want to select the option to have the workspace populated immediately, which means the files will be brought down from the server to my workstation.
Once the new workspace is created and populated, I have everything I need to start working.
Now I'm going to make a small change to a file called Glob.C. I'll submit this change back into the server depot, leaving a comment to document the work I’ve done in the changelist. I'm just adding a comment, using my favorite editor.
Of course, I could work on many files over the course of a couple of hours, and submit them all together in a changelist.
As a side note, this submission would probably fire off a build-test-code review cycle, which we aren’t going to show in this video, but to learn more, watch some of our tutorial on Helix Swarm.
After finishing my work on the dev 2.3 stream, and passing the build and code review, I am ready to promote the change to main, but I look at the stream graph and see the merge arrow from main down to dev 2.3 is lit up.
This means there are changes in main that I need to merge down to my dev 2.3 Stream. If I try to copy my changes up before merging down, I’ll get a warning message, which is why the copy up arrow is red.
This would probably be the result of work being completed and promoted by another team member ahead of my own.
So, to account for this change, I'm going to right-click on the dev 2.3 stream and select merge, integrate. This brings up the merge dialogue. The Source Stream is already filled out.
With Streams, Helix Core knows where merges to dev 2.3 usually come from. Of course, you can work outside the normal merge channels if you need to. Merging a hotfix is an example where the normal procedures might not be followed. The other default merge options look fine for this example, so I'll go ahead and click Merge.
The merged changes are now waiting in a new pending changelist, for me to examine. To do that, I select the changelist, right-click for the menu, and choose Resolve Files.
I'm going to go ahead and let Helix Core automatically merge whatever it can, so I'll pick the automatic resolve option and then click the auto resolve button. There are no merge conflicts, so that actually took care of everything.
What happens next depends on your workflow. For the purpose of the demo let’s assume an automated build/test cycle is completed on the post-merge dev 2.3, and everything still works correctly. With that done, the changes become part of dev 2.3 by submitting the pending changelist.
Now I'm ready to copy my completed dev 2.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 dev 2.3, which we call a copy or promote operation.
I'll start by right-clicking on main and choose the copy option. Now, as part of this operation, P4V is actually going to move my workspace up to Main, but I'll come back to that a little bit later on. A copy up is a simple operation. We're going to be copying from dev 2.3 up to Main. I'll accept the rest of the default options in the copy dialogue, and have P4V automatically submit my files after the copy is done.
Notice the merge arrows between main and dev 2.3, are no longer lit up. This means there's nothing waiting to be merged or copied between main and dev 2.3.
Now that we've seen how to do some basic work and branching, merging and copying, let's discuss workspace options. In the Stream Graph, notice the workspace icon on main. That tells me that I'm currently working in the main stream.
I can reuse a single workspace and move that workspace from stream to stream. This makes sense if I have a lot of data in my workspace and don’t want to have several copies on my workstation. It's also convenient if I have tooling already configured for this workspace.
To move a workspace in the stream graph, I just pick up the workspace icon and drag it to the rel 2.1 stream. Behind the scenes, Helix Core only updated the files in the workspace that actually differ between those two streams. So, moving a workspace is usually pretty fast and easy. And notice in the workspace tab I'm still using my Aruna_jam_dev_2.3 workspace, but it's now pointing at the rel 2.1 stream.
Streams is an easy way to start working in a project, and provides great flexibility to merge changes between code lines and switch from task to task.