Add release workflow

Author: krisgeus

.github/workflows/whirl-release.yml

@@ -7,14 +7,14 @@ jobs:
   deploy:
     runs-on: ubuntu-latest
     permissions:
-      contents: write  # for actions/upload-release-asset to upload release asset
+      contents: write  # for upload release asset
     steps:
       - uses: actions/checkout@v2
 
       - name: Run git-archive command to create a release artifact
         run: git archive --format=tar.gz --prefix=whirl/ --output=whirl-release.tar.gz HEAD
 
-      - name: upload linux artifact
+      - name: upload Whirl release artifact
         env:
           GITHUB_TOKEN: ${{ github.token }}
         run: |

README.md

@@ -42,7 +42,18 @@ export PATH=<target directory of whirl>:${PATH}
 
 ### Use the release
 
-Download the release artifact
+Download the [latest Whirl release artifact](https://github.com/godatadriven/whirl/releases/download/latest/whirl-release.tar.gz)
+
+Extract the file (for example into `/usr/local/opt`)
+
+```bash
+tar -xvzf whirl-release.tar.gz -C /usr/local/opt
+```
+
+Make sure the whirl script is available on your path
+```bash
+export PATH=/usr/local/opt/whirl:$PATH
+```
 
 ## Usage
 
@@ -57,18 +68,22 @@ $ whirl --help
 
 #### Starting whirl
 
-The default action is to start the DAG in your current directory. It expects an environment to be configured. You can pass this as a command line argument or you can configure it in a `.whirl.env` file. (See [Configuring environment variables](#configuring-environment-variables).) The environment refers to a directory with the same name in the `envs` directory located near the _whirl_ script.
+The default action is to start the DAG in your current directory.
+
+With the `[-x example]` commandline argument you can run whirl from anywhere and tell whirl which example dag to run. The example refers to a directory with the same name in the `examples` directory located near the _whirl_ script.
+
+Whirl expects an environment to be configured. You can pass this as a command line argument `[-e environment]` or you can configure it as environment variable `WHIRL_ENVIRONMENT` in a `.whirl.env` file. (See [Configuring environment variables](#configuring-environment-variables).) The environment refers to a directory with the same name in the `envs` directory located near the _whirl_ script.
 
 ```bash
-$ whirl [start] [-d <directory>] [-e <environment>]
+$ whirl [-x example] [-e <environment>] [start]
 ```
 
 Specifying the `start` command line argument is a more explicit way to start _whirl_.
 
 #### Stopping whirl
 
 ```bash
-$ whirl stop [-d <directory>] [-e <environment>]
+$ whirl  [-x example] [-e <environment>] stop
 ```
 Stops the configured environment.
 
@@ -140,8 +155,6 @@ Each example contains it's own README file to explain the specifics of that exam
 
 #### Generic running of examples
 
-From within the example directory the `whirl` command can be executed. 
-
 To run a example:
 
 ```bash
@@ -150,6 +163,13 @@ $ cd ./examples/<example-dag-directory>
 $ whirl -e <environment to use>
 ```
 
+or
+```bash
+$
+# Note: here we pass the whirl environment as a command-line argument. It can also be configured with the WHIRL_ENVIRONMENT variable
+$ whirl -x <example to run> -e <environment to use>
+```
+
 Open your browser to [http://localhost:5000](http://localhost:5000) to access the Airflow UI. Manually enable the DAG and watch the pipeline run to successful completion.
 
 

whirl

@@ -347,6 +347,7 @@ logs() {
 usage() {
   echo "usage: ${BASH_SOURCE[0]} [-h|--help] [-e|--environment env] [start|stop|ci]"
   echo "  -h|--help                          display usage"
+  echo "  -x|--example example               specify example to run"
   echo "  -e|--environment environment       specify environment to use"
   echo "  -d|--directory environment_folder  specify the folder that contains the environments (defaults to SCRIPT_DIR)"
   echo "  -l|--logs servicename              tail the logs of the service"