For release v0.5

Author: timthepost

README.md

@@ -1,39 +1,38 @@
 # pre-commit hooks for Swimm
 
-Utilizing [pre-commit](https://pre-commit.com/), you can enable Swimm checks to run prior to the review cycle. In order to get started, you'll need to [install pre-commit](https://pre-commit.com/#install) (pip, brew and other methods are available). 
+Utilizing [pre-commit](https://pre-commit.com/), you can enable Swimm checks to run locally with other lints, prior to the PR review cycle. In order to get started, you'll need to [install pre-commit](https://pre-commit.com/#install) (pip, brew and other methods are available).
 
-After that, there are two ways you can make use of the hooks hosted here:
+Then, select which hook you want to run. **Most** users won't need to modify the.
 
 ## For Those That Don't Need To Modify The Hooks:
 
 If you don't need to modify any of the hooks, you can simply pull in the hook configurations from this repository.
 
 Put the following contents into `.pre-commit-config.yaml` in the root of your repository (create it if needed):
 
-```
+```yml
 repos:
   - repo: https://github.com/swimmio/pre-commit
-    rev: v0.3 # (Check release tags for the latest release, current preview release is v0.4)
+    rev: v0.5 # (Check release tags for the latest release, current is v0.5)
     hooks:
       - id: swimm-verify # Verifies documentation is in sync
 ```
-That should be all you need if you just want to run the verification checks locally, and treat failure like any other test failing.
-
-There are two more hooks explained in [hooks/](https://github.com/swimmio/pre-commit/tree/main/hooks) which you can optionally enable:
-
-```
-      - id: swimm-verify-nonblocking # Verifies documentation but doesn't block, opens an issue instead.
-      - id: swimm-export # (Illustrative only) Shows how you could set up your existing hooks to export your documentation to Docusaurus, Notion, Etc.
-```
+That should be all you need if you just want to run the verification checks locally, and treat failure like any other test failing. If you need to open an issue instead of failing, use `swimm-verify-nonblocking` as described in [hooks/](https://github.com/swimmio/pre-commit/tree/main/hooks).
 
 If you already have a `.pre-commit-config.yaml` file, add the swimm checks as a new `- repo` section, wherever you'd like them to run. Note that if you have failure mode set to fast, no other checks will run if documentation can't be verified, so we recommend adding Swimm as the last (or close to last) check. 
 
-Note: The hooks are currently implemented as bash scripts; Windows users need to run WSL in order to use them for now. I'm planning to do it agnostically just with Python in the near future.
+Note: The hooks are currently implemented as bash scripts; Windows users need to run WSL in order to use them for now.
 
 ## For Those Who Want To Modify The Hooks
 
-Fork this repository to your orgainzation, make the changes you want, and tag in a release for your team to use. Then, your team will need to 
-point their configuration files to the forked repo (and specify your version) rather than pointing them here.
+Grab the script in [hooks/](https://github.com/swimmio/pre-commit/tree/main/hooks) that you want to use as a base, and just include it in your own pre-commit repository. Your configuration will look something like this:
 
+```yml
+repos:
+  - repo: https://github.com/your-organization/your-pre-commit-repo
+    rev: vX.Y # (Your version nuymbers)
+    hooks:
+      - id: swimm-verify
+```
 
-If you create any new hooks that you think others might find useful, feel free to send over a PR. 
+You can also fork this repository to your own organization, commit whatever changes you wish to make, and then tag in a new release for your teammates to use. 

hooks/README.md

@@ -2,42 +2,30 @@
 
  - `swimm-verify` will run Swimm's verification checks, and exit nonzero if they fail. Recommended.
  - `swimm-verify-nonblocking` (v0.4 only) Like swimm-verify, but will always return successfully. Webooks are used to open an issue if verification fails.
- - `swimm-export` An example of exporting Swimm docs for third-party documentation hubs like Confluence & Notion
 
 All hooks will currently work with the web or desktop version of swimm. If you
 don't have the CLI component, the hook will download it for you and clean up
 after it runs. 
 
 If you use the web version, you'll need `curl` and `wget` installed.
 
+If the environmental variable `SWIMM_VERIFY_WEBHOOK` is set, the scripts will
+send a POST request to the URL with the field `context` containing the output
+of the `swimm_cli verify` command. This is useful for build automation, such 
+as automatically opening an issue if the non-blocking hook fails.
+
+An example of how this can be automated is given as a ["Zap" template at Zapier](https://zapier.com),
+which consists of a webhook that creates a card on a Trello board. You can switch
+the Trello part for Github, Jira, BitBucket and *most* other forges.
+
 ## The `swimm-verify` Hook:
 
 This is the simplest (and most ideal) configuration. The verification check will
 return nonzero if something requires attention. Documentation failing verification
 will be treated just like any other test that fails.
 
-## The `swimm-verify-nonblocking` Hook (v0.4 only):
-
-This hook allows documentation verification checks to proceed, and will (optionally)
-call a webhook that opens an issue at Github, Bitbucket, Jira, Trello Or anything
-else that has an API using [Zapier](http://zapier.com).
-
-We have a template you can use to set this up quickly at:
-
-https://zapier.com/shared/82c84601a5f678127c6cada740e64279c7fdd274
-
-But any webook conveniently accessed with curl will work.
-
-
-To set it up:
-
- 1. Start with the template linked above. Grab your unique webhook URL.
- 2. Change the workflow to open the issue whereever it works for you.
- 3. Make sure anyone using the extension has the environmental variable `SWIMM_VERIFY_WEBHOOK` set to the webhook URL.
- 4. If the verification fails, the webhook will open an issue with the output letting you know what needs fixed.
-
-## The `swimm-export` Hook:
+## The `swimm-verify-nonblocking` Hook (v0.4+ only):
 
-This hook demonstrates exporting Swimm documentation to other formats for
-publishing in other knowledge collections like Docusaurus, Notion, Confluence
-and others. This is only currently usable for the Desktop version.
+This hook is just like `swimm-verify`, but it will always exit successfully, even if
+the documentation verification check fails. If used on a conunction with a webhook,
+you can let the build proceed and create an issue with a deadline to complete.

hooks/swimm-verify-nonblocking.sh

@@ -74,7 +74,6 @@ webhook() {
         warn "Could not read enviormental variable SWIMM_VERIFY_WEBHOOK so I don't know who to call."
         return
     }
-    printf "Hi! I'm Webhook!\nContext is:\n%s\nDialing: %s\n" "$@" "$SWIMM_VERIFY_WEBHOOK"
     $BIN_CURL --data "context=$@" $SWIMM_VERIFY_WEBHOOK | grep success 2>&1 >/dev/null
     if [ $? -eq 0 ]; then
         printf "Webhook succeeded!"

hooks/swimm-verify.sh

@@ -75,7 +75,6 @@ webhook() {
         warn "Could not read enviormental variable SWIMM_VERIFY_WEBHOOK so I don't know who to call."
         return
     }
-    printf "Hi! I'm Webhook!\nContext is:\n%s\nDialing: %s\n" "$@" "$SWIMM_VERIFY_WEBHOOK"
     $BIN_CURL --data "context=$@" $SWIMM_VERIFY_WEBHOOK | grep success 2>&1 >/dev/null
     if [ $? -eq 0 ]; then
         printf "Webhook succeeded!"