Combining all the matching pages into one doc.

README.md

@@ -98,6 +98,9 @@ The use cases for the space cloner is centered around repeated runs between two
 # How the space cloner works
 Please see the [how it works page](docs/HowItWorks.md).
 
+# How matching works
+Please see the [how matching works page](docs/HowMatchingWorks.md).
+
 # Sensitive variables
 Please see the page [sensitive variables](docs/SensitiveVariables.md) to see how sensitive variables are handled.
 

docs/CloneLibraryVariableSetParameterReference.md

@@ -39,13 +39,13 @@ The variable scoping parameters are:
 - `VariableAccountScopingMatch`: How to handle when a variable in a project or library variable set is scoped to an Account in the source but not all environments are in the destination.  Default is `SkipUnlessPartialMatch`.
 - `VariableCertificateScopingMatch`: How to handle when a variable in a project or library variable set is scoped to an Certificate in the source but not all environments are in the destination.  Default is `SkipUnlessPartialMatch`.
 
-See more how this works in the [How Scope Cloning Works Documentation](HowScopeCloningWorks.md).
+See more how this works in the [how matching works page](HowMatchingWorks.md).
 
 ## Options
 
 The values for these options are either `True`, `False` or `null`.  Null will cause the default parameter to be used.
 
-- `OverwriteExistingVariables`: Indicates if all existing variables (except sensitive variables) should be overwritten.  The default is `false`.  Options are `true`, `false`, or `AddNewWithDefaultValue`. See how [Variable Matching Works](HowVariableMatchingWorks.md)
+- `OverwriteExistingVariables`: Indicates if all existing variables (except sensitive variables) should be overwritten.  The default is `false`.  Options are `true`, `false`, or `AddNewWithDefaultValue`. See more how this works in the [how matching works page](HowMatchingWorks.md).
 - `IgnoreVersionCheckResult`: Indicates if the script should ignore version checks rules and proceed with the clone.  This should only be used for cloning to test instances of Octopus Deploy.  The default is `false`.
 - `SkipPausingWhenIgnoringVersionCheckResult`: When `IgnoreVersionCheckResult` is set to true the script will pause for 20 seconds when it detects a difference to let you cancel.  You can skip that check by setting this to `true`. This should only be used for cloning to test instances of Octopus Deploy.  The default is `false`.
 - `WhatIf`: Set to `$true` if you want to see everything this script will do without it actually doing the work.  Set to `$false` to have it do the work.  Defaults to `$false`.

docs/CloneSpaceParameterReference.md

@@ -81,15 +81,15 @@ The infrastructure scoping parameters are:
 - `InfrastructureTenantScopingMatch`: How to handle when a Deployment Target or Account is scoped to 1 to N Tenants in the source but not all environments are in the destination.  Default is `SkipUnlessPartialMatch`.
 - `VariableTenantTagsScopingMatch`: How to handle when a Deployment Target or Account is scoped to to 1 to N Tenant Tags in the source but not all Tenant Tags are in the destination.  Default is `SkipUnlessPartialMatch`.
 
-See more how this works in the [How Scope Cloning Works Documentation](HowScopeCloningWorks.md).
+See more how this works in the [how matching works page](HowMatchingWorks.md).
 
 ## Options
 
 The values for these options are either `True`, `False` or `null`.  Null will cause the default parameter to be used.
 
 - `OverwriteExistingCustomStepTemplates`: Indicates if existing custom step templates (not community step templates) should be overwritten.  Useful when you make a change to a step template, you want to move over to another instance.  Defaults to `false`.
 - `OverwriteExistingLifecyclesPhases`: Indicates you want to overwrite the phases on existing lifecycles.  This is useful when you have an updated lifecycle you want to be applied another space/instance.  You will want to leave this to false if the destination lifecycle has different phases.  The default is `false`.  You can also send in `NeverCloneLifecyclePhases` which means it will never clone a lifecycle phase ever.  This is useful when you need to have instances with completely separate environments.
-- `OverwriteExistingVariables`: Indicates if all existing variables (except sensitive variables) should be overwritten.  The default is `false`.  Options are `true`, `false`, or `AddNewWithDefaultValue`. See how [Variable Matching Works](HowVariableMatchingWorks.md)
+- `OverwriteExistingVariables`: Indicates if all existing variables (except sensitive variables) should be overwritten.  The default is `false`.  Options are `true`, `false`, or `AddNewWithDefaultValue`. See more how this works in the [how matching works page](HowMatchingWorks.md).
 - `CloneProjectChannelRules`: Indicates if the project channel rules should be cloned and overwrite existing channel rules.  The default is `false`.
 - `CloneProjectDeploymentProcess`: Indicates if the project deployment process should be cloned.  Set this to `false` to only clone project runbooks.  The default is `true`.
 - `CloneProjectRunbooks`: Indicates if project runbooks should be cloned.  Set this to `false` to only clone the project deployment process.  The default is `true`.
@@ -98,5 +98,5 @@ The values for these options are either `True`, `False` or `null`.  Null will ca
 - `CloneTenantVariables`: Indicates if tenant variables should be cloned.  The default is`false`.
 - `IgnoreVersionCheckResult`: Indicates if the script should ignore version checks rules and proceed with the clone.  This should only be used for cloning to test instances of Octopus Deploy.  The default is `false`.
 - `SkipPausingWhenIgnoringVersionCheckResult`: When `IgnoreVersionCheckResult` is set to true the script will pause for 20 seconds when it detects a difference to let you cancel.  You can skip that check by setting this to `true`. This should only be used for cloning to test instances of Octopus Deploy.  The default is `false`.
-- `ProcessCloningOption`: Tells the cloner how to handle the situation where steps are in a destination runbook or deployment process but not in the source.  Options are `KeepAdditionalDestinationSteps` or `SourceOnly`.  The default is `KeepAdditionalDestinationSteps`.
+- `ProcessCloningOption`: Tells the cloner how to handle the situation where steps are in a destination runbook or deployment process but not in the source.  Options are `KeepAdditionalDestinationSteps` or `SourceOnly`.  The default is `KeepAdditionalDestinationSteps`. See more how this works in the [how matching works page](HowMatchingWorks.md).
 - `WhatIf`: Set to `$true` if you want to see everything this script will do without it actually doing the work.  Set to `$false` to have it do the work.  Defaults to `$false`.

docs/CloneSpaceProjectParameterReference.md

@@ -92,15 +92,15 @@ The infrastructure scoping parameters are:
 - `InfrastructureTenantScopingMatch`: How to handle when a Deployment Target or Account is scoped to 1 to N Tenants in the source but not all environments are in the destination.  Default is `SkipUnlessPartialMatch`.
 - `VariableTenantTagsScopingMatch`: How to handle when a Deployment Target or Account is scoped to to 1 to N Tenant Tags in the source but not all Tenant Tags are in the destination.  Default is `SkipUnlessPartialMatch`.
 
-See more how this works in the [How Scope Cloning Works Documentation](HowScopeCloningWorks.md).
+See more how this works in the [how matching works page](HowMatchingWorks.md).
 
 ## Options
 
 The values for these options are either `True`, `False` or `null`.  Null will cause the default parameter to be used.
 
 - `OverwriteExistingCustomStepTemplates`: Indicates if existing custom step templates (not community step templates) should be overwritten.  Useful when you make a change to a step template, you want to move over to another instance.  Defaults to `false`.
 - `OverwriteExistingLifecyclesPhases`: Indicates you want to overwrite the phases on existing lifecycles.  This is useful when you have an updated lifecycle you want to be applied another space/instance.  You will want to leave this to false if the destination lifecycle has different phases.  The default is `false`.
-- `OverwriteExistingVariables`: Indicates if all existing variables (except sensitive variables) should be overwritten.  The default is `false`.  Options are `true`, `false`, or `AddNewWithDefaultValue`. See how [Variable Matching Works](HowVariableMatchingWorks.md)
+- `OverwriteExistingVariables`: Indicates if all existing variables (except sensitive variables) should be overwritten.  The default is `false`.  Options are `true`, `false`, or `AddNewWithDefaultValue`. See more how this works in the [how matching works page](HowMatchingWorks.md).
 - `CloneProjectChannelRules`: Indicates if the project channel rules should be cloned and overwrite existing channel rules.  The default is `false`.
 - `CloneProjectDeploymentProcess`: Indicates if the project deployment process should be cloned.  Set this to `false` to only clone project runbooks.  The default is `true`.
 - `CloneProjectRunbooks`: Indicates if project runbooks should be cloned.  Set this to `false` to only clone the project deployment process.  The default is `true`.
@@ -110,5 +110,5 @@ The values for these options are either `True`, `False` or `null`.  Null will ca
 - `CloneTenantVariables`: Indicates if tenant variables should be cloned.  The default is`false`.
 - `IgnoreVersionCheckResult`: Indicates if the script should ignore version checks rules and proceed with the clone.  This should only be used for cloning to test instances of Octopus Deploy.  The default is `false`.
 - `SkipPausingWhenIgnoringVersionCheckResult`: When `IgnoreVersionCheckResult` is set to true the script will pause for 20 seconds when it detects a difference to let you cancel.  You can skip that check by setting this to `true`. This should only be used for cloning to test instances of Octopus Deploy.  The default is `false`.
-- `ProcessCloningOption`: Tells the cloner how to handle the situation where steps are in a destination runbook or deployment process but not in the source.  Options are `KeepAdditionalDestinationSteps` or `SourceOnly`.  The default is `KeepAdditionalDestinationSteps`.
+- `ProcessCloningOption`: Tells the cloner how to handle the situation where steps are in a destination runbook or deployment process but not in the source.  Options are `KeepAdditionalDestinationSteps` or `SourceOnly`.  The default is `KeepAdditionalDestinationSteps`. See more how this works in the [how matching works page](HowMatchingWorks.md).
 - `WhatIf`: Set to `$true` if you want to see everything this script will do without it actually doing the work.  Set to `$false` to have it do the work.  Defaults to `$false`.

docs/HowItWorks.md

@@ -86,11 +86,8 @@ This script was designed to be run multiple times with the same parameters.  It
 - Targets (match by name)
 - Tenants (match by name) -> it will add missing projects to the tenant
 
-## Scope Matching
-Imagine if your source instance had the environments `Development` and `Test` while the destination only had `Production`.  You have a step scoped to only run on `Development`.  When that step is cloned over what should it do?  See more how this works in the [How Scope Cloning Works Documentation](HowScopeCloningWorks.md).
-
-## Variable Matching
-Variable matching is very complex as variables can have a variety of scoping associated with them.  See how [Variable Matching Works](HowVariableMatchingWorks.md).
+## Matching
+A lot of what the space cloner does is match data between the source instance and the destination instance.  See [how matching works](HowMatchingWorks.md) for more information.
 
 ## Limitations
 Because this is hitting the Octopus Restful API, it cannot decrypt items from the Octopus Database.  To decrypt items from the Octopus database, you'll need access to the master key and the database.  This script was designed to run on an Octopus Cloud instance.  You, the user, do not have access to that information.  
@@ -100,31 +97,6 @@ Please see the [sensitive variables page](SensitiveVariables.md) for more inform
 ## Simple Relationship Management
 The process does not attempt to walk a tree of dependencies.  It loads up all the necessary data from the source and destination.  It will attempt to find the corresponding ID in the destination space when it comes across an ID in the source space.  If it cannot find a matching item, it removes that binding.  
 
-## Process Cloning
-This script assumes that when you clone a deployment process, you want to add missing steps but leave existing steps.
-
-I have a deployment process on my source, where I added a new step.
-
-![](../img/process-source-added-step.png)
-
-My destination deployment process has a new step on the end that is not in the source.
-
-![](../img/destination-deployment-process-before-sync.png)
-
-After the sync is finished, the new step was added, and the additional step was left as is.
-
-![](../img/destination-deployment-process-after-sync.png)
-
-The rules for cloning a deployment process are:
-
-- Clone steps not found in the destination process
-- Leave existing steps as is
-- The source process is the source of truth for step order.  It will ensure the destination deployment process order matches.  It will then add additional steps found in the deployment process not found in the source to the end of the deployment process.
-
-### Override Default Process Cloning Behavior
-
-A new parameter has been added to the process cloner, `ProcessCloningOption`.  That allows you to overwrite the default behavior.  The options are `KeepAdditionalDestinationSteps` or `SourceOnly`.  The default is `KeepAdditionalDestinationSteps`.  Setting this parameter to `SourceOnly` will result in any steps in the destination not on the source to be removed.
-
 ## Targets and Workers
 
 The script will clone your targets and workers.  However, there are a few key items you should know.