Prepare 1.0.0 release.

CHANGELOG.md

@@ -4,11 +4,19 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
-## [Unreleased]
- - Current development changes [ to be moved to release ]
+## Unreleased
+ - ...
+
+## [1.0.0] - 2020-10-18
+ - Initial Major Release (no functional changes from [0.0.4])
+
+## [0.0.4] - 2020-10-17
+ - Releases 0.0.2 and 0.0.3 contained no functional changes and were [attempts to avoid the example usages getting reformatted by the Orb Repository](https://discuss.circleci.com/t/orb-example-formatting-gets-mangled-after-publishing/37816).
+ - Add a note to the example usages explaining that it's clearer to check the source.
 
 ## [0.0.1] - 2020-10-17
  - Initial Release
 
-
+[1.0.0]: https://github.com/adamu/slack-webhook-orb/releases/tag/1.0.0
+[0.0.4]: https://github.com/adamu/slack-webhook-orb/releases/tag/0.0.4
 [0.0.1]: https://github.com/adamu/slack-webhook-orb/releases/tag/0.0.1

README.md

@@ -2,9 +2,36 @@
 
 ## Setup
 
-## Usage Examples
+1. [Create a webhook](https://api.slack.com/messaging/webhooks).
+2. [Generate a JSON payload](https://app.slack.com/block-kit-builder).
+3. Place the webhook in a [CircleCI environment variable](https://circleci.com/docs/2.0/env-vars/) (`SLACK_WEBHOOK` by default, but customizable).
+4. Call the orb:
+   ```yml
+   slack-webhook/send-message:
+     json-payload: |
+       {
+         "blocks": [
+           {
+             "type": "section",
+             "text": {
+               "type": "mrkdwn",
+               "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
+             }
+           }
+         ]
+       }
+   ```
 
-See the usage examples on the orb's [CircleCI Orb Repository listing](https://circleci.com/developer/orbs/orb/adamu/slack-webhook).
+## Usage
+
+The `json-payload` argument must always be provided.
+
+There are three ways to provide the webhook URL:
+1. Via the `SLACK_WEBHOOK` environment variable.
+2. Via a custom environment variable. Provide the name with the `webhook-url-env-var` parameter.
+3. Directly to the `send-message` command with the `webhook-url` parameter.
+
+See the full examples on the orb's [CircleCI Orb Repository listing](https://circleci.com/developer/orbs/orb/adamu/slack-webhook#usage-examples).
 
 ## Changelog
 

slack-webhook-orb.yml

@@ -1,11 +1,9 @@
 version: 2.1
 
-description: |
-  A simple orb to send fully-customized Slack messages via Slack webhooks.
-  To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
+description: A simple orb to send fully-customized Slack messages via Slack webhooks.
 
 display:
-  source_url: "https://github.com/adamu/slack-webhook-orb"
+  source_url: https://github.com/adamu/slack-webhook-orb
 
 commands:
   send-message:
@@ -51,10 +49,14 @@ examples:
   webhook-url:
     description: |
       Provide the webhook URL directly in the webhook-url parameter.
-      Note that this leaks the Webhook URL in your CircleCI config and the CircleCI logs,
-      so using one of the environment variable option is preferred.
-      Provide the Slack JSON payload in the json-payload parameter.
-      The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Note that this leaks the Webhook URL in your CircleCI config and the CircleCI logs - using one of the environment variable options below is recommended.
+
+      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
+      The json payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
+
     usage:
       version: 2.1
 
@@ -69,22 +71,26 @@ examples:
             - slack-webhook/send-message:
                 webhook-url: https://hooks.slack.com/...
                 json-payload: |
-                    {
-                      "blocks": [
-                        {
-                          "type": "section",
-                          "text": {
-                            "type": "mrkdwn",
-                            "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
-                          }
+                  {
+                    "blocks": [
+                      {
+                        "type": "section",
+                        "text": {
+                          "type": "mrkdwn",
+                          "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
                         }
-                      ]
-                    }
+                      }
+                    ]
+                  }
   environment-variable:
     description: |
-      Provide the webhook URL in the SLACK_WEBHOOK environment variable on CircleCI.
+      Set the webhook URL in the SLACK_WEBHOOK environment variable on CircleCI.
       When using this method, only the json-payload parameter needs to be supplied.
+
+      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
       The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
     usage:
       version: 2.1
 
@@ -98,23 +104,25 @@ examples:
           steps:
             - slack-webhook/send-message:
                 json-payload: |
-                    {
-                      "blocks": [
-                        {
-                          "type": "section",
-                          "text": {
-                            "type": "mrkdwn",
-                            "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
-                          }
+                  {
+                    "blocks": [
+                      {
+                        "type": "section",
+                        "text": {
+                          "type": "mrkdwn",
+                          "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
                         }
-                      ]
-                    }
+                      }
+                    ]
+                  }
   custom-environment-variable:
     description: |
-      Supply the webhook URL in a custom environment variable configured on CircleCI,
-      and provide the name of the environment variable in the webhook-url-env-var parameter.
-      Provide the Slack JSON payload in the json-payload parameter.
+      Set the webhook URL in a custom environment variable configured on CircleCI, and provide the name of the environment variable in the webhook-url-env-var parameter.
+
+      To generate a webhook URL, please see the Slack instructions: https://api.slack.com/messaging/webhooks
       The payload can be generated with the Slack Block Kit Builder: https://app.slack.com/block-kit-builder
+
+      Unfortunately the json payload example below is reformatted by the CircleCI documentation generator. Please check the original in the Orb Source at the bottom of the page for an easier to read example.
     usage:
       version: 2.1
 
@@ -129,14 +137,14 @@ examples:
             - slack-webhook/send-message:
                 webhook-url-env-var: CUSTOM_SLACK_WEBHOOK_VARIABLE
                 json-payload: |
-                    {
-                      "blocks": [
-                        {
-                          "type": "section",
-                          "text": {
-                            "type": "mrkdwn",
-                            "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
-                          }
+                  {
+                    "blocks": [
+                      {
+                        "type": "section",
+                        "text": {
+                          "type": "mrkdwn",
+                          "text": "Hello from <https://github.com/adamu|@adamu>'s `slack-webhook` CircleCi orb! 👋"
                         }
-                      ]
-                    }
+                      }
+                    ]
+                  }