docs: update readme and cli usage text

gmolki · Nov 6, 2017 · ebce7d8 · ebce7d8
1 parent 89d5a04
commit ebce7d8
Show file tree

Hide file tree

Showing 4 changed files with 152 additions and 4 deletions.
diff --git a/README.md b/README.md
@@ -1,12 +1,106 @@
 # Pact Broker Client
 
-A client for the Pact Broker. Publishes pacts to, and retrieves pacts from, the pact broker.
+A client for the Pact Broker. Publishes pacts to, and retrieves pacts from, the pact broker. The functionality is available via a CLI, or via Ruby configuration code.
 
 [![Build Status](https://travis-ci.org/pact-foundation/pact_broker-client.svg?branch=master)](https://travis-ci.org/pact-foundation/pact_broker-client)
 
-## Usage
+## Usage - CLI
 
-You will need an instance of a [Pact Broker](https://github.com/pact-foundation/pact_broker). It's URL will be used below in the configuration for the Consumer and the Provider. eg. http://pact-broker.my.org
+### publish
+
+```
+Usage:
+  pact-broker publish PACT_DIRS_OR_FILES ... -a, --consumer-app-version=CONSUMER_APP_VERSION -b, --broker-base-url=BROKER_BASE_URL
+
+Options:
+  -a, --consumer-app-version=CONSUMER_APP_VERSION          # The consumer application version
+  -b, --broker-base-url=BROKER_BASE_URL                    # The base URL of the Pact Broker
+  -u, [--broker-username=BROKER_USERNAME]                  # Pact Broker basic auth username
+  -p, [--broker-password=BROKER_PASSWORD]                  # Pact Broker basic auth password
+  -t, [--tag=TAG]                                          # Tag name for consumer version. Can be specified multiple times.
+  -g, [--tag-with-git-branch], [--no-tag-with-git-branch]  # Tag consumer version with the name of the current git branch. Default: false
+  -v, [--verbose], [--no-verbose]                          # Verbose output. Default: false
+
+Publish pacts to a Pact Broker.
+```
+
+### create-version-tag
+
+```
+Usage:
+  pact-broker create-version-tag -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL -e, --version=VERSION
+
+Options:
+  -a, --pacticipant=PACTICIPANT                            # The pacticipant name
+  -e, --version=VERSION                                    # The pacticipant version
+  -t, [--tag=TAG]                                          # Tag name for pacticipant version. Can be specified multiple times.
+  -g, [--tag-with-git-branch], [--no-tag-with-git-branch]  # Tag pacticipant version with the name of the current git branch. Default: false
+  -b, --broker-base-url=BROKER_BASE_URL                    # The base URL of the Pact Broker
+  -u, [--broker-username=BROKER_USERNAME]                  # Pact Broker basic auth username
+  -p, [--broker-password=BROKER_PASSWORD]                  # Pact Broker basic auth password
+  -v, [--verbose], [--no-verbose]                          # Verbose output. Default: false
+
+Add a tag to a pacticipant version
+```
+
+### can-i-deploy
+
+*This feature is in beta release, and backwards compatibility is NOT guaranteed.*
+You will need the latest version of the Pact Broker for this feature to work.
+
+```
+Usage:
+  pact-broker can-i-deploy -a, --pacticipant=PACTICIPANT -b, --broker-base-url=BROKER_BASE_URL
+
+Options:
+  -a, --pacticipant=PACTICIPANT            # The pacticipant name. Use once for each pacticipant being checked.
+  -e, [--version=VERSION]                  # The pacticipant version. Must be entered after the --pacticipant that it relates to.
+  -l, [--latest=[TAG]]                     # Use the latest pacticipant version. Optionally specify a TAG to use the latest version with the specified tag.
+  -b, --broker-base-url=BROKER_BASE_URL    # The base URL of the Pact Broker
+  -u, [--broker-username=BROKER_USERNAME]  # Pact Broker basic auth username
+  -p, [--broker-password=BROKER_PASSWORD]  # Pact Broker basic auth password
+  -o, [--output=OUTPUT]                    # json or table
+                                           # Default: table
+  -v, [--verbose], [--no-verbose]          # Verbose output. Default: false
+
+Description:
+  Returns exit code 0 or 1, indicating whether or not the specified pacticipant versions are compatible. Prints out the
+  relevant pact/verification details.
+
+  The environment variables PACT_BROKER_BASE_URL, PACT_BROKER_USERNAME and PACT_BROKER_PASSWORD may be used instead of
+  their respective command line options.
+
+  SCENARIOS
+
+  Check the status of the pacts for a pacticipant version:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT --version VERSION --broker-base-url BROKER_BASE_URL
+
+  Check the status of the pacts for the latest pacticipant version:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT --latest --broker-base-url BROKER_BASE_URL
+
+  Check the status of the pacts for the latest pacticipant version for a given tag:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT --latest TAG --broker-base-url BROKER_BASE_URL
+
+  Check the status of the pacts between two (or more) specific pacticipant versions:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT1 --version VERSION1 --pacticipant PACTICIPANT2 --version VERSION2
+  --broker-base-url BROKER_BASE_URL
+
+  Check the status of the pacts between the latest versions of two (or more) pacticipants:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT1 --latest --pacticipant PACTICIPANT2 --latest --broker-base-url
+  BROKER
+
+  Check the status of the pacts between the latest versions of two (or more) pacticipants with a given tag:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT1 --latest TAG1 --pacticipant PACTICIPANT2 --latest TAG2
+  --broker-base-url BROKER_BASE_URL
+```
+
+## Usage - Ruby
 
 ### Consumer
 
@@ -64,4 +158,6 @@ Pact.service_provider "My Provider" do
 end
 ```
 
+
+
 [wiki-tags]: https://github.com/pact-foundation/pact_broker/wiki/Using-tags
diff --git a/lib/pact_broker/client/cli/broker.rb b/lib/pact_broker/client/cli/broker.rb
@@ -15,7 +15,8 @@ module CLI
       class PactPublicationError < ::Thor::Error; end
 
       class Broker < CustomThor
-        desc 'can-i-deploy', "Returns exit code 0 or 1, indicating whether or not the specified application versions are compatible."
+        desc 'can-i-deploy', ''
+        long_desc File.read(File.join(File.dirname(__FILE__), '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."

diff --git a/lib/pact_broker/client/cli/can_i_deploy_long_desc.txt b/lib/pact_broker/client/cli/can_i_deploy_long_desc.txt
@@ -0,0 +1,31 @@
+Returns exit code 0 or 1, indicating whether or not the specified pacticipant versions are compatible. Prints out the relevant pact/verification details.
+
+WARNING! This feature is in beta release, and backwards compatibility is NOT guaranteed. You will need the latest version of the Pact Broker for this feature to work.
+
+The environment variables PACT_BROKER_BASE_URL_BASE_URL, PACT_BROKER_BASE_URL_USERNAME and PACT_BROKER_BASE_URL_PASSWORD may be used instead of their respective command line options.
+
+SCENARIOS
+
+Check the status of the pacts for a pacticipant version:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT --version VERSION --broker-base-url BROKER_BASE_URL
+
+Check the status of the pacts for the latest pacticipant version:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT --latest --broker-base-url BROKER_BASE_URL
+
+Check the status of the pacts for the latest pacticipant version for a given tag:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT --latest TAG --broker-base-url BROKER_BASE_URL
+
+Check the status of the pacts between two (or more) specific pacticipant versions:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT1 --version VERSION1 --pacticipant PACTICIPANT2 --version VERSION2 --broker-base-url BROKER_BASE_URL
+
+Check the status of the pacts between the latest versions of two (or more) pacticipants:
+
+  $ pact-broker can-i-deploy --pacticipant PACTICIPANT1 --latest --pacticipant PACTICIPANT2 --latest --broker-base-url BROKER_BASE_URL
+
+Check the status of the pacts between the latest versions of two (or more) pacticipants with a given tag:
+
+$ pact-broker can-i-deploy --pacticipant PACTICIPANT1 --latest TAG1 --pacticipant PACTICIPANT2 --latest TAG2 --broker-base-url BROKER_BASE_URL
diff --git a/script/generate-cli-usage.sh b/script/generate-cli-usage.sh
@@ -0,0 +1,20 @@
+echo '### publish'
+echo ''
+echo '```'
+echo "$(bundle exec bin/pact-broker help publish)"
+echo '```'
+echo ''
+echo '### create-version-tag'
+echo ''
+echo '```'
+echo "$(bundle exec bin/pact-broker help create-version-tag)"
+echo '```'
+echo ''
+echo '### can-i-deploy'
+echo ''
+echo '*This feature is in beta release, and backwards compatibility is NOT guaranteed.*'
+echo 'You will need the latest version of the Pact Broker for this feature to work.'
+echo ''
+echo '```'
+echo "$(bundle exec bin/pact-broker help can-i-deploy)"
+echo '```'