= A brief monologue on p4 merge, p4 copy, and merge down/copy up

== What does merge do?

'p4 merge' takes content from one stream and combines it with content in another, preserving unique changes on both sides. After running 'p4 merge' the target stream may or may not contain the content of the source stream, depending on how the user chooses to resolve the merge files.

'p4 merge' uses the copious amount of integration history Perforce stores to calculate which changes should be propagated and the best resolve option for each file.

Integration records will be created by 'p4 merge' to show where the target content came from. Integration record types will vary depending on the type of resolve for each file.

== What does copy do?

'p4 copy' takes content from one stream and replaces the content of another stream. After running 'p4 copy' the target stream will look identical to the source stream.

'p4 copy' uses a simple content comparison mechanism to figure out which changes should be propagated. Files will be added, edited, and deleted as appropriate in the target to ensure that the target exactly matches the source.

Integration records will be created by 'p4 copy' to show where the target content came from. All integration records will of the type "copied from/to".

= The mechanics of merge down, copy up

Merge down, copy up is based on the notion that is important to make destabilizing changes as far away from shipping code as possible. In this model only small critical fixes are made to release streams. Most work occurs either in a shared mainline, or in development streams which are even less stable. We talk about release streams as being firm, or risk adverse; development streams are reffered to as soft, or risk tolerant.

It is generally considered a best practice to merge down changes from a firmer or more risk adverse stream, and then copy up changes from a softer stream. The goal of this model is to make destabilizing changes as far from shipped code as possible. It is assumed that firmer code is generally well tested and more stable, and should always be included in softer child streams.

By copying up, a developer can feel confident that all tests that passed in the development stream will pass when promoted up to a mainline or release line. This prevents wayward merges from divergent streams from breaking tests in the target stream.

With streams, we recommend that users always merge changes down from their firmer parent before copying their own changes up. Otherwise their copied changes would potentially overwrite important changes from the parent. The system enforces this by throwing an error if a user attempts to copy up when there are changes that have not yet been merged down. In the best case, a user updates their development stream with changes from the firmer parent, runs any automated tests, and if they pass copies the code back up to the firmer parent to share with their co-workers.

In our modern day and age, it is equally viable to always merge down and then merge up. Preferably you would still merge down all changes from the firmer parent so that you can run automated tests in the softer, or more risk tolerant, stream. Copy up is still encouraged when possible as it ensures that the source and target are identical. In the merge down, merge up world there is a slight chance that divergences introduced by ignoring changes will cause test failures.

In the end, 'p4 copy' is aware of integration history and attempts not to destroy it, but when calculating the results of a copy operation it ignores it, relying instead on a content comparison. This makes it possible for copy to ensure that changes that were ignored from the parent are properly rolled back.

Let me know if some pictures would help and I can put some together. =)