feat: rename target to application-instance for record-deployment and…

… record-undeployment (backwards compatible)

README.md

@@ -275,29 +275,33 @@ Usage:
   pact-broker record-deployment --environment=ENVIRONMENT -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL -e, --version=VERSION
 
 Options:
-  -a, --pacticipant=PACTICIPANT            
+  -a, --pacticipant=PACTICIPANT                      
               # The name of the pacticipant that was deployed.
-  -e, --version=VERSION                    
+  -e, --version=VERSION                              
               # The pacticipant version number that was deployed.
-      --environment=ENVIRONMENT            
+      --environment=ENVIRONMENT                      
               # The name of the environment that the pacticipant version was
                 deployed to.
-      [--target=TARGET]                    
-              # Optional. The target of the deployment - a logical identifer
-                required to differentiate deployments when there are multiple
-                instances of the same application in an environment.
-  -o, [--output=OUTPUT]                    
+      [--application-instance=APPLICATION_INSTANCE]  
+              # Optional. The application instance to which the deployment has
+                occurred - a logical identifer required to differentiate
+                deployments when there are multiple instances of the same
+                application in an environment. This field was called 'target'
+                in a beta release.
+      [--target=TARGET]                              
+              # Renamed to application_instance
+  -o, [--output=OUTPUT]                              
               # json or text
               # Default: text
-  -b, --broker-base-url=BROKER_BASE_URL    
+  -b, --broker-base-url=BROKER_BASE_URL              
               # The base URL of the Pact Broker
-  -u, [--broker-username=BROKER_USERNAME]  
+  -u, [--broker-username=BROKER_USERNAME]            
               # Pact Broker basic auth username
-  -p, [--broker-password=BROKER_PASSWORD]  
+  -p, [--broker-password=BROKER_PASSWORD]            
               # Pact Broker basic auth password
-  -k, [--broker-token=BROKER_TOKEN]        
+  -k, [--broker-token=BROKER_TOKEN]                  
               # Pact Broker bearer token
-  -v, [--verbose], [--no-verbose]          
+  -v, [--verbose], [--no-verbose]                    
               # Verbose output. Default: false
 ```
 
@@ -310,28 +314,34 @@ Usage:
   pact-broker record-undeployment --environment=ENVIRONMENT -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL
 
 Options:
-  -a, --pacticipant=PACTICIPANT            
+  -a, --pacticipant=PACTICIPANT                      
               # The name of the pacticipant that was undeployed.
-      --environment=ENVIRONMENT            
+      --environment=ENVIRONMENT                      
               # The name of the environment that the pacticipant version was
                 undeployed from.
-      [--target=TARGET]                    
+      [--application-instance=APPLICATION_INSTANCE]  
+              # Optional. The application instance from which the application
+                is being undeployed - a logical identifer required to
+                differentiate deployments when there are multiple instances of
+                the same application in an environment. This field was called
+                'target' in a beta release.
+      [--target=TARGET]                              
               # Optional. The target that the application is being undeployed
                 from - a logical identifer required to differentiate
                 deployments when there are multiple instances of the same
                 application in an environment.
-  -o, [--output=OUTPUT]                    
+  -o, [--output=OUTPUT]                              
               # json or text
               # Default: text
-  -b, --broker-base-url=BROKER_BASE_URL    
+  -b, --broker-base-url=BROKER_BASE_URL              
               # The base URL of the Pact Broker
-  -u, [--broker-username=BROKER_USERNAME]  
+  -u, [--broker-username=BROKER_USERNAME]            
               # Pact Broker basic auth username
-  -p, [--broker-password=BROKER_PASSWORD]  
+  -p, [--broker-password=BROKER_PASSWORD]            
               # Pact Broker basic auth password
-  -k, [--broker-token=BROKER_TOKEN]        
+  -k, [--broker-token=BROKER_TOKEN]                  
               # Pact Broker bearer token
-  -v, [--verbose], [--no-verbose]          
+  -v, [--verbose], [--no-verbose]                    
               # Verbose output. Default: false
 ```
 
@@ -469,8 +479,8 @@ Description:
   support for environments, deployments and releases. For documentation on how to use can-i-deploy with tags, please see
   https://docs.pact.io/pact_broker/client_cli/can_i_deploy_usage_with_tags/
 
-  Before `can-i-deploy` can be used, the relevant environment resources must first be created in the Pact Broker using the `create-environment` command. The "test"
-  and "production" environments will have been seeded for you. You can check the existing environments by running `pact-broker list-environments`. See
+  Before `can-i-deploy` can be used, the relevant environment resources must first be created in the Pact Broker using the `create-environment` command. The
+  "test" and "production" environments will have been seeded for you. You can check the existing environments by running `pact-broker list-environments`. See
   https://docs.pact.io/pact_broker/client_cli/readme#environments for more information.
 
   $ pact-broker create-environment --name "uat" --display-name "UAT" --no-production
@@ -480,17 +490,17 @@ Description:
 
   $ pact-broker record-deployment --pacticipant Foo --version 173153ae0 --environment uat
 
-  Before an application is deployed or released to an environment, the can-i-deploy command must be run to check that the application version is safe to deploy with
-  the versions of each integrated application that are already in that environment.
+  Before an application is deployed or released to an environment, the can-i-deploy command must be run to check that the application version is safe to deploy
+  with the versions of each integrated application that are already in that environment.
 
   $ pact-broker can-i-deploy --pacticipant PACTICIPANT --version VERSION --to-environment ENVIRONMENT
 
   Example: can I deploy version 173153ae0 of application Foo to the test environment?
 
   $ pact-broker can-i-deploy --pacticipant Foo --version 173153ae0 --to-environment test
 
-  Can-i-deploy can also be used to check if arbitrary versions have a successful verification. When asking "Can I deploy this application version with the latest version
-  from the main branch of another application" it functions as a "can I merge" check.
+  Can-i-deploy can also be used to check if arbitrary versions have a successful verification. When asking "Can I deploy this application version with the
+  latest version from the main branch of another application" it functions as a "can I merge" check.
 
   $ pact-broker can-i-deploy --pacticipant Foo 173153ae0 \ --pacticipant Bar --latest main
 
@@ -628,8 +638,8 @@ Options:
 ```
 
 Description:
-  Create a curl command that executes the request that you want your webhook to execute, then replace "curl" with "pact-broker create-webhook" and add the consumer,
-  provider, event types and broker details. Note that the URL must be the first parameter when executing create-webhook.
+  Create a curl command that executes the request that you want your webhook to execute, then replace "curl" with "pact-broker create-webhook" and add the
+  consumer, provider, event types and broker details. Note that the URL must be the first parameter when executing create-webhook.
 
   Note that the -u option from the curl command clashes with the -u option from the pact-broker CLI. When used in this command, the -u will be used as a curl
   option. Please use the --broker-username or environment variable for the Pact Broker username.
@@ -686,9 +696,9 @@ Options:
 ```
 
 Description:
-  Create a curl command that executes the request that you want your webhook to execute, then replace "curl" with "pact-broker create-or-update-webhook" and add the
-  consumer, provider, event types and broker details. Note that the URL must be the first parameter when executing create-or-update-webhook and a uuid must
-  also be provided. You can generate a valid UUID by using the `generate-uuid` command.
+  Create a curl command that executes the request that you want your webhook to execute, then replace "curl" with "pact-broker create-or-update-webhook" and
+  add the consumer, provider, event types and broker details. Note that the URL must be the first parameter when executing create-or-update-webhook and a uuid
+  must also be provided. You can generate a valid UUID by using the `generate-uuid` command.
 
   Note that the -u option from the curl command clashes with the -u option from the pact-broker CLI. When used in this command, the -u will be used as a curl
   option. Please use the --broker-username or environment variable for the Pact Broker username.

doc/pacts/markdown/Pact Broker Client - Pact Broker.md

@@ -2129,6 +2129,7 @@ Given **version 5556b8149bf8bac76bc30f50a8a2dd4c22c85f30 of pacticipant Foo exis
     "Accept": "application/hal+json"
   },
   "body": {
+    "applicationInstance": "blue",
     "target": "blue"
   }
 }

lib/pact_broker/client/cli/deployment_commands.rb

@@ -14,16 +14,18 @@ def self.included(thor)
             method_option :pacticipant, required: true, aliases: "-a", desc: "The name of the pacticipant that was deployed."
             method_option :version, required: true, aliases: "-e", desc: "The pacticipant version number that was deployed."
             method_option :environment, required: true, desc: "The name of the environment that the pacticipant version was deployed to."
-            method_option :target, default: nil, required: false, desc: "Optional. The target of the deployment - a logical identifer required to differentiate deployments when there are multiple instances of the same application in an environment."
+            method_option :application_instance, default: nil, required: false, desc: "Optional. The application instance to which the deployment has occurred - a logical identifer required to differentiate deployments when there are multiple instances of the same application in an environment. This field was called 'target' in a beta release."
+            method_option :target, hidden: true, default: nil, required: false, desc: "Renamed to application_instance"
             output_option_json_or_text
             shared_authentication_options
 
             def record_deployment
+              $stderr.puts("WARN: target has been renamed to application-instance") if options.target
               params = {
                 pacticipant_name: options.pacticipant,
                 version_number: options.version,
                 environment_name: options.environment,
-                target: options.target
+                application_instance: options.application_instance || options.target
               }
               execute_deployment_command(params, "RecordDeployment")
             end
@@ -32,15 +34,17 @@ def record_deployment
             long_desc "Note that use of this command is only required if you are permanently removing an application instance from an environment. It is not required if you are deploying over a previous version, as record-deployment will automatically mark the previously deployed version as undeployed for you. See #{RECORD_UNDEPLOYMENT_HELP_URL} for more information."
             method_option :pacticipant, required: true, aliases: "-a", desc: "The name of the pacticipant that was undeployed."
             method_option :environment, required: true, desc: "The name of the environment that the pacticipant version was undeployed from."
+            method_option :application_instance, default: nil, required: false, desc: "Optional. The application instance from which the application is being undeployed - a logical identifer required to differentiate deployments when there are multiple instances of the same application in an environment. This field was called 'target' in a beta release."
             method_option :target, default: nil, required: false, desc: "Optional. The target that the application is being undeployed from - a logical identifer required to differentiate deployments when there are multiple instances of the same application in an environment."
             output_option_json_or_text
             shared_authentication_options
 
             def record_undeployment
+              $stderr.puts("WARN: target has been renamed to application-instance") if options.target
               params = {
                 pacticipant_name: options.pacticipant,
                 environment_name: options.environment,
-                target: options.target
+                application_instance: options.application_instance || options.target
               }
               execute_deployment_command(params, "RecordUndeployment")
             end

lib/pact_broker/client/deployments/record_deployment.rb

@@ -6,12 +6,12 @@ module Deployments
       class RecordDeployment < PactBroker::Client::Deployments::RecordRelease
         def initialize(params, options, pact_broker_client_options)
           super
-          @target = params.fetch(:target)
+          @application_instance = params.fetch(:application_instance)
         end
 
         private
 
-        attr_reader :target
+        attr_reader :application_instance
 
         def action
           "deployment"
@@ -22,12 +22,13 @@ def action_relation_name
         end
 
         def record_action_request_body
-          { target: target }.compact
+          # for backwards compatibility with old broker
+          { applicationInstance: application_instance, target: application_instance }.compact
         end
 
         def result_text_message
-          if target
-            "#{super} (target #{target})"
+          if application_instance
+            "#{super} (application instance #{application_instance})"
           else
             super
           end

lib/pact_broker/client/deployments/record_undeployment.rb

@@ -8,7 +8,7 @@ def initialize(params, options, pact_broker_client_options)
           super
           @pacticipant_name = params.fetch(:pacticipant_name)
           @environment_name = params.fetch(:environment_name)
-          @target = params.fetch(:target)
+          @application_instance = params.fetch(:application_instance)
         end
 
         private
@@ -21,7 +21,7 @@ def do_call
           end
         end
 
-        attr_reader :pacticipant_name, :environment_name, :target
+        attr_reader :pacticipant_name, :environment_name, :application_instance
 
         def currently_deployed_versions_link
           environment_resource._link("pb:currently-deployed-deployed-versions", "pb:currently-deployed-versions") or raise PactBroker::Client::Error.new(not_supported_message)
@@ -31,14 +31,19 @@ def currently_deployed_version_entities_for_pacticipant
           @deployed_version_links ||= currently_deployed_versions_link.get!(pacticipant: pacticipant_name).embedded_entities!("deployedVersions")
         end
 
-        def currently_deployed_version_entities_for_pacticipant_and_target
+        def currently_deployed_version_entities_for_pacticipant_and_instance
           currently_deployed_version_entities_for_pacticipant.select do | entity |
-            entity.target == target
+            if application_instance
+              entity.applicationInstance == application_instance || entity.target == application_instance
+            else
+              entity.applicationInstance == nil && entity.target == nil
+            end
+
           end
         end
 
         def undeployed_versions_resources
-          @undeployed_versions_resources ||= currently_deployed_version_entities_for_pacticipant_and_target.collect do | entity |
+          @undeployed_versions_resources ||= currently_deployed_version_entities_for_pacticipant_and_instance.collect do | entity |
             entity._link!("self").patch(currentlyDeployed: false)
           end
         end
@@ -75,7 +80,7 @@ def success_result_text_message(undeployed_versions_resource)
           message = "Recorded #{action} of #{pacticipant_name}"
           message = "#{message} version #{version.number}" if (version && version.number)
           message = "#{message} from #{environment_name} environment"
-          message = "#{message} (target #{target})" if target
+          message = "#{message} (application instance #{application_instance})" if application_instance
           message
         end
 
@@ -92,19 +97,22 @@ def error_text
             "No pacticipant with name '#{pacticipant_name}' found."
           else
             if currently_deployed_version_entities_for_pacticipant.any?
-              target_does_not_match_message
+              application_instance_does_not_match_message
             else
               "#{pacticipant_name} is not currently deployed to #{environment_name} environment. Cannot record undeployment."
             end
           end
         end
 
-        def target_does_not_match_message
-          potential_targets = currently_deployed_version_entities_for_pacticipant.collect(&:target).collect { |target| target || "<no target>"}
-          if target
-            "#{pacticipant_name} is not currently deployed to target '#{target}' in #{environment_name} environment. Please specify one of the following targets to record the undeployment from: #{potential_targets.join(", ")}"
+        def application_instance_does_not_match_message
+          potential_application_instances = currently_deployed_version_entities_for_pacticipant.collect{|e| e.applicationInstance || e.target }
+
+          if application_instance
+            omit_text = potential_application_instances.include?(nil) ? "omit the application instance to undeploy from the anonymous instance" : nil
+            specify_text = potential_application_instances.compact.any? ? "specify one of the following application instances to record the undeployment from: #{potential_application_instances.compact.join(", ")}" : nil
+            "#{pacticipant_name} is not currently deployed to application instance '#{application_instance}' in #{environment_name} environment. Please #{[omit_text, specify_text].compact.join(" or ")}."
           else
-            "Please specify one of the following targets to record the undeployment from: #{potential_targets.join(", ")}"
+            "Please specify one of the following application instances to record the undeployment from: #{potential_application_instances.compact.join(", ")}"
           end
         end