chore(record-deployment): add target

lib/pact_broker/client/cli/broker.rb

@@ -15,7 +15,7 @@ class Broker < CustomThor
         using PactBroker::Client::HashRefinements
 
         desc 'can-i-deploy', ''
-        long_desc File.read(File.join(File.dirname(__FILE__), 'can_i_deploy_long_desc.txt'))
+        long_desc File.read(File.join(__dir__, 'can_i_deploy_long_desc.txt'))
 
         method_option :pacticipant, required: true, aliases: "-a", desc: "The pacticipant name. Use once for each pacticipant being checked."
         method_option :version, required: false, aliases: "-e", desc: "The pacticipant version. Must be entered after the --pacticipant that it relates to."
@@ -173,10 +173,11 @@ def list_latest_pact_versions(*required_but_ignored)
 
           ignored_and_hidden_potential_options_from_environment_variables
           desc "record-deployment", "Record deployment of a pacticipant version to an environment"
+          long_desc File.read(File.join(__dir__, 'record_deployment_long_desc.txt'))
           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 :replaced_previous_deployed_version, type: :boolean, default: true, required: false, desc: "Whether or not this deployment replaced the previous deployed version. If it did, the previous deployed version of this pacticipant will be marked as undeployed in the Pact Broker."
+          method_option :target, default: nil, required: false, desc: "The target of the deployment - a logical identifer that represents where the application version was deployed to. See the usage docs for information on when to use this."
           method_option :output, aliases: "-o", desc: "json or text", default: 'text'
           shared_authentication_options
 
@@ -186,7 +187,7 @@ def record_deployment
               pacticipant_name: options.pacticipant,
               version_number: options.version,
               environment_name: options.environment,
-              replaced_previous_deployed_version: options.replaced_previous_deployed_version,
+              target: options.target,
               output: options.output
             }
             result = PactBroker::Client::Versions::RecordDeployment.call(

lib/pact_broker/client/cli/record_deployment_long_desc.txt

@@ -0,0 +1,55 @@
+The record-deployment command is used to allow the Pact Broker to keep track of which version(s) of an application are currently deployed in each environment. It is used to keep track of applications that are deployed to known instances. If you are releasing a client library or mobile application to a repository or application store, please use record-release instead.
+
+## Examples
+
+
+record-deployment --pacticipant Foo --version 6897aa95e --environment production
+record-deployment --pacticipant Foo --version 6897aa95e --environment production --target blue
+record-deployment --pacticipant Foo --version 6897aa95e --environment production --target green
+
+## Target
+
+The "target" field is used to distinguish between deployed versions of an application within the same environment, and most importantly, to identify which previously deployed version has been replaced by the current deployment. The Pact Broker only allows one unique combination of pacticipant/environment/target to be considered the "currently deployed" one, and any call to record a deployment will cause the previously deployed version with the same pacticipant/environment/target to be automatically marked as undeployed (mimicking the real world process of "deploying over" a previous version).
+
+### Use cases
+
+#### There is a single instance of an application deployed within an environment and deployments of integrated applications are NOT likely to happen during the deployment window of this application
+
+eg.
+
+* the window of time when there are multiple versions in prod is small
+* or there aren't many other integrations
+* or deployments happen rarely
+* or the same team controls all the deployments and generally only runs one deployment at a time
+
+In this case, there is no need to specify a target. The call to record deployment should be done at the end of the deployment and it will automatically mark the version of Foo that was previously the currently deployed version as undeployed. Only one version of the pacticipant is ever considered to be currently deployed at a time.
+
+eg.
+
+# actual call to deploy here...
+record-deployment --pacticipant Foo --version 6897aa95e --environment production
+
+#### There is a single instance of an application deployed within an environment and but deployments of integrated applications ARE likely to happen during the deployment window of this application
+
+eg.
+* the window of time when there are multiple versions in prod is large
+* or there are many integrations
+* or deployments happen often
+* or there are many different teams deploying and deployments aren't coordinated
+
+To allow multiple versions to be considered currently deployed at the same time, use two different targets, and call the first record-deployment at the start of the deployment process and a second one at the end.
+
+eg.
+
+This will use the targets "blue" and "green" to model stages of the deployment.
+
+record-deployment --pacticipant Foo --version 6897aa95e --environment production --target blue
+# actual call to deploy here...
+record-deployment --pacticipant Foo --version 6897aa95e --environment production --target green
+
+After the first call to record-deployment, there will be two versions considered currently deployed - the "blue" one that was just recorded, and the one from the previous "green" deployment. After the second call to record-deployment, there is only one version considered currently deployed - both "blue" and "green" targets will be have version 6897aa95e deployed to them.
+
+
+#### There are multiple permanent application versions deployed to the same environment
+
+TBC

lib/pact_broker/client/versions/record_deployment.rb

@@ -19,7 +19,7 @@ def initialize(params, pact_broker_base_url, pact_broker_client_options)
           @pacticipant_name = params.fetch(:pacticipant_name)
           @version_number = params.fetch(:version_number)
           @environment_name = params.fetch(:environment_name)
-          @replaced_previous_deployed_version = params.fetch(:replaced_previous_deployed_version)
+          @target = params.fetch(:target)
           @output = params.fetch(:output)
           @pact_broker_client_options = pact_broker_client_options
         end
@@ -36,7 +36,7 @@ def call
         private
 
         attr_reader :pact_broker_base_url, :pact_broker_client_options
-        attr_reader :pacticipant_name, :version_number, :environment_name, :replaced_previous_deployed_version, :output
+        attr_reader :pacticipant_name, :version_number, :environment_name, :target, :output
         attr_reader :deployed_version_resource
 
         def check_environment_exists
@@ -75,13 +75,13 @@ def get_pacticipant_version
         end
 
         def record_deployment_request_body
-          { replacedPreviousDeployedVersion: replaced_previous_deployed_version }
+          { replacedPreviousDeployedVersion: target }
         end
 
         def result_message
           if output == "text"
             message = "Recorded deployment of #{pacticipant_name} version #{version_number} to #{environment_name} in #{pact_broker_name}."
-            suffix = replaced_previous_deployed_version ? " Marked previous deployed version as undeployed." : ""
+            suffix = target ? " Marked previous deployed version as undeployed." : ""
             message + suffix
           elsif output == "json"
             deployed_version_resource.response.raw_body

lib/pact_broker/client/versions/record_undeployment.rb

@@ -46,7 +46,7 @@ def call
         private
 
         attr_reader :pact_broker_base_url, :pact_broker_client_options
-        attr_reader :pacticipant_name, :version_number, :environment_name, :replaced_previous_deployed_version, :output
+        attr_reader :pacticipant_name, :version_number, :environment_name, :target, :output
         attr_reader :deployed_version_resource, :undeployment_entities
 
         def version_resource

script/record-deployment.sh

@@ -1,4 +1,2 @@
 PACT_BROKER_FEATURES=deployments bundle exec bin/pact-broker record-deployment \
-   --pacticipant foo-consumer --version 1 --environment prod --broker-base-url http://localhost:9292 --no-replaced_previous_deployed_version
-
-
+   --pacticipant foo-consumer --version 1 --environment prod --broker-base-url http://localhost:9292

spec/lib/pact_broker/client/versions/record_deployment_spec.rb

@@ -15,14 +15,14 @@ class Versions
             stub_request(:get, broker_base_url).to_return(status: 200, body: index_body_hash.to_json, headers: { "Content-Type" => "application/hal+json" }  )
           end
 
-          let(:replaced_previous_deployed_version) { true }
+          let(:target) { true }
 
           let(:params) do
             {
               pacticipant_name: "Foo",
               version_number: "1",
               environment_name: "test",
-              replaced_previous_deployed_version: replaced_previous_deployed_version,
+              target: target,
               output: "text"
             }
           end
@@ -57,15 +57,15 @@ class Versions
             end
           end
 
-          context "when replaced_previous_deployed_version is false" do
+          context "when target is false" do
             before do
               allow_any_instance_of(RecordDeployment).to receive(:check_if_command_supported)
               allow_any_instance_of(RecordDeployment).to receive(:check_environment_exists)
               allow_any_instance_of(RecordDeployment).to receive(:record_deployment)
               allow_any_instance_of(RecordDeployment).to receive(:pact_broker_name).and_return("")
             end
 
-            let(:replaced_previous_deployed_version) { false }
+            let(:target) { false }
 
             let(:deployed_version_resource) do
               double('PactBroker::Client::Hal::Entity', response: double('response', headers: response_headers) )

spec/service_providers/record_deployment_spec.rb

@@ -10,13 +10,13 @@
   let(:version_number) { "5556b8149bf8bac76bc30f50a8a2dd4c22c85f30" }
   let(:environment_name) { "test" }
   let(:output) { "text" }
-  let(:replaced_previous_deployed_version) { true }
+  let(:target) { true }
   let(:params) do
     {
       pacticipant_name: pacticipant_name,
       version_number: version_number,
       environment_name: environment_name,
-      replaced_previous_deployed_version: replaced_previous_deployed_version,
+      target: target,
       output: output
     }
   end
@@ -148,14 +148,14 @@ def mock_record_deployment
         path: "/HAL-REL-PLACEHOLDER-PB-RECORD-DEPLOYMENT-FOO-5556B8149BF8BAC76BC30F50A8A2DD4C22C85F30-TEST",
         headers: post_request_headers,
         body: {
-          replacedPreviousDeployedVersion: replaced_previous_deployed_version
+          replacedPreviousDeployedVersion: target
         }
       )
       .will_respond_with(
         status: 201,
         headers: pact_broker_response_headers,
         body: {
-          replacedPreviousDeployedVersion: replaced_previous_deployed_version
+          replacedPreviousDeployedVersion: target
         }
       )
   end
@@ -176,7 +176,7 @@ def mock_record_deployment
       let(:output) { "json" }
 
       it "returns the JSON payload" do
-        expect(JSON.parse(subject.message)).to eq "replacedPreviousDeployedVersion" => replaced_previous_deployed_version
+        expect(JSON.parse(subject.message)).to eq "replacedPreviousDeployedVersion" => target
       end
     end
   end