November 9, 2015

Under the Hood with 2015.2 P4D Streams Enhancements, Part Two

Healthcare
Helix Core

In my previous post, I revealed a few of the smaller changes to streams that were introduced in the P4D 2015.2 server release. The largest enhancement, though, is the ability to open and submit streams in much the same way as you do with files.

#1211694 (Bug #77627) **                Stream specifications may now be opened and submitted, enabling                them to be staged on a particular client and tested before                being submitted atomically in a changelist along with a set of                files.  See 'p4 help streamcmds' for more information.

To manage this new concept of an open stream spec, three new "p4 stream" subcommands have been added:

  •     p4 stream edit
  •     p4 stream resolve [-a<flag>] [-n] [-o]
  •     p4 stream revert

Note that just as you can only open a file if it's mapped in your current client, you can only open a stream spec when you are using a client of that stream. 

P4 Stream Edit

The "p4 stream edit" command opens the current stream, creating an open spec that is a copy of the latest submitted spec (its head revision, if you like).  When the spec is opened, only some fields are affected; these fields are marked in the spec with an "# open" comment on the relevant lines. Any changes you make to those fields are visible to your client alone. Similarly, changes made by other clients to those fields against the submitted version of the spec are not reflected in your open copy.

P4 Stream Resolve

The "p4 stream resolve" command pulls other clients' submitted stream spec changes into your open stream spec and, in general, works much like "p4 resolve". One difference of note is that "p4 stream resolve -af" handles conflicts by appending the conflicting blocks to each other (there are no conflict markers, so be careful).

P4 Stream Revert

The "p4 stream revert" command abandons your open changes and returns you to the submitted version of the stream spec.

Changes that you've made to your open stream spec are made available to other users via the existing "p4 submit" and "p4 shelve" commands. 

By default, if you have an open stream spec, it is attached to any shelve or submit operation -- unlike a file, the open stream spec is not associated with a particular pending changelist prior to submit or shelve, because the stream spec potentially affects files across multiple pending changelists.  To exclude the stream spec from one of these operations, use the new "-Af" flag to specify that only files should be acted upon.

In Conclusion

So what's the point of this whole concept of an open stream spec?

One benefit is that, like making a tricky change to a file, you can test a stream spec change and not have it break someone else.  For example, suppose you need to change which branch of external library you "import", and you're not sure if it'll build right with the code in your stream.  Rather than running "p4 stream", making the change, and finding out you've just broken the build for everyone, now you can do "p4 stream edit" before running "p4 stream", and test your change before it affects anyone else.

Continuing that same example, suppose that the new library does break your build, and to fix it you need to modify some of the files in your stream.  If someone else syncs the new versions of the files before the stream is updated, the build breaks; if someone else gets the updated stream before you submit the new versions of the files, the build also breaks.  But by opening the stream, opening the files, making all your changes, and submitting them all in one changelist, you prevent anyone else from ever seeing a "broken" state; everyone else syncs the updated files right along with the updated stream-generated view.

Note that for now, if you never run the new "p4 stream edit" command, none of this will affect you in the slightest (with one exception: if someone else opens their stream spec and then shelves it, you'll get their version of the stream spec opened in your workspace when you unshelve that changelist).  You are still able to edit a stream directly with the "p4 stream" command, and in that case you will still see the old behavior of having that update be instantly available to everyone else.

We're planning to do even more with streams in upcoming releases, so keep watching this space!