chore: Document return behavior of cdk diff (#1446)

The `cdk diff` command intentionally returns non-zero when a difference is found,
similar to how the POSIX `diff` command behaves (returning 0 when no difference is
found, 1 when some difference is found, and >1 when an error occurred). This
behavior was however undocumented, possibly leading to user confusion.

This change adds a note in `cdk --help` that mentions the exit code 1 will be used
when a difference is found.

Fixes #1440

packages/aws-cdk/bin/cdk.ts

@@ -59,7 +59,7 @@ async function parseCommandLineArguments() {
       .option('require-approval', { type: 'string', choices: [RequireApproval.Never, RequireApproval.AnyChange, RequireApproval.Broadening], desc: 'what security-sensitive changes need manual approval' }))
     .command('destroy [STACKS..]', 'Destroy the stack(s) named STACKS', yargs => yargs
       .option('force', { type: 'boolean', alias: 'f', desc: 'Do not ask for confirmation before destroying the stacks' }))
-    .command('diff [STACK]', 'Compares the specified stack with the deployed stack or a local template file', yargs => yargs
+    .command('diff [STACK]', 'Compares the specified stack with the deployed stack or a local template file, and returns with status 1 if any difference is found', yargs => yargs
       .option('template', { type: 'string', desc: 'the path to the CloudFormation template to compare with' })
       .option('strict', { type: 'boolean', desc: 'do not filter out AWS::CDK::Metadata resources', default: false }))
     .command('metadata [STACK]', 'Returns all metadata associated with this stack')