Update documentation

README.md

@@ -5,17 +5,20 @@
 [ci-integration-badge]: https://github.com/kvrhdn/gha-buildevents/workflows/Integration/badge.svg
 [ci-integration-link]: https://github.com/kvrhdn/gha-buildevents/actions?query=workflow%3AIntegration
 
-This GitHub Action installs and initializes [Honeycomb's buildevents tool][buildevents]. It populates the trace with metadata from the workflow and will always send a trace for the entire build, even if the build failed.
+This GitHub Action instruments your workflows using [Honeycomb's buildevents tool][buildevents]. It populates the trace with metadata from the workflow and will always send a trace for the build, even if the build failed.
 
-To learn more about buildevents and how to use it, checkout [honeycombio/buildevents][buildevents].
+`gha-buildevents` has to be added to every job that should be instrumented. Every job will create a separate trace.
+
+⚠️ Limitations:
 
-⚠️ This action is still in development, for now use the version from the main branch `kvrhdn/gha-buildevents@main`. I plan to introduce a `v1` tag eventually.
+- this action only works on Linux hosts
+- if downloading buildevents fails or if running buildevents failed (i.e. a bug in buildevents) the entire job will fail
 
 [buildevents]: https://github.com/honeycombio/buildevents
 
 ## How to use it
 
-Run the action somewhere in the beginning of your worflow:
+Put the action in the beginning of your worflow:
 
 ```yaml
 - uses: kvrhdn/gha-buildevents@main
@@ -35,25 +38,21 @@ Run the action somewhere in the beginning of your worflow:
   # 'buildevents build' will automatically run as a post action.
 ```
 
-From then on `buildevents` is present on the path. `gha-buildevents` sets an environment varible `TRACE_ID` (this currently defaults to the run number). The build ID should be used with all buildevents commands to ensure the trace is continued.
+`gha-buildevents` is a _wrapping action_. This means it has a post section which will run at the end of the build, after all other steps. In this final step the trace is finalized using `buildevents build`. Since this step runs always, even if the job failed, you don't have to worry about traces not being sent.
 
-```yaml
-  # Record the start of the step and, for conveniance, set the step ID that will
-  # be used for all commands.
-- run: |
-    echo ::set-env name=STEP_ID::0
-    echo ::set-env name=STEP_START::$(date +%s)
+### Inputs
 
-  # Wrap the commands that should be traced with 'buildevents cmd'
-- run: |
-    buildevents cmd $TRACE_ID $STEP_ID sleep-5 -- sleep 5
+Name         | Required | Description                                          | Type   | Default
+-------------|----------|------------------------------------------------------|--------|--------
+`apikey`     | yes      | API key used to communicate with the Honeycomb API.  | string | 
+`dataset`    | yes      | Honeycomb dataset to use.                            | string |
+`job-status` | yes      | The job status, must be set to `${{ job.status }}`.  | string |
 
-  # Wrap up the step
-- run: |
-    buildevents step $TRACE_ID $STEP_ID $STEP_START 'step 1'
-```
+### Outputs
 
-`gha-buildevents` is a _wrapping action_. This means it has a post section which will run at the end of the build, after all other steps. In this final step the trace is finalized using `buildevents build`. Since this step runs always, even if the job failed, you don't have to worry about traces not being sent.
+No outputs are set, but the following environment variables are set:
+
+- `TRACE_ID`: the trace ID, this defaults to the run number and should be used in all invocation of `buildevents`
 
 ## Example
 
@@ -63,19 +62,29 @@ This workflow will create the following trace in Honeycomb:
 
 ![Trace created in Honeycomb](./example-trace.png)
 
-### Inputs
+## Adding additional spans
 
-Name         | Required | Description                                          | Type   | Default
--------------|----------|------------------------------------------------------|--------|--------
-`apikey`     | yes      | API key used to communicate with the Honeycomb API.  | string | 
-`dataset`    | yes      | Honeycomb dataset to use.                            | string |
-`job-status` | yes      | The job status, must be set to `${{ job.status }}`.  | string |
+After `gha-buildevents` has run, `buildevents` will be available on the path. You can use the `buildevents` exectable to add additional spans.
 
-### Outputs
+`gha-buildevents` sets an environment varible `TRACE_ID`. The trace ID should be used with all buildevents commands to ensure the trace is continued.
 
-No outputs are set (yet), but the following environment variables are set:
+To learn more about buildevents and how to use it, checkout [honeycombio/buildevents][buildevents].
 
-- `TRACE_ID`: the trace ID, this defaults to the run number and should be used in all invocation of `buildevents`
+```yaml
+  # Record the start of the step and, for conveniance, set the step ID that will
+  # be used for all commands.
+- run: |
+    echo ::set-env name=STEP_ID::0
+    echo ::set-env name=STEP_START::$(date +%s)
+
+  # Wrap the commands that should be traced with 'buildevents cmd'
+- run: |
+    buildevents cmd $TRACE_ID $STEP_ID sleep-5 -- sleep 5
+
+  # Wrap up the step
+- run: |
+    buildevents step $TRACE_ID $STEP_ID $STEP_START 'step 1'
+```
 
 ## License
 

action.yaml

@@ -1,6 +1,6 @@
-name: gha-buildevents
+name: Honeycomb Buildevents
 author: Koenraad Verheyden
-description: Integrate Honeycomb's buildevents tool in your workflow
+description: Add observability to your GitHub Actions workflows 
 
 branding:
   icon: activity

doc/release-procedure.md

@@ -0,0 +1,14 @@
+# Release procedure
+
+`gha-buildevents` follows [the recommendation from the GitHub Actions team][actions-versioning], namely that each release has a semantic version (i.e. `v1.0.1`). We also provide a major version tag (i.e. `v1`) that binds to the latest semantic version.
+
+[actions-versioning]: https://github.com/actions/toolkit/blob/master/docs/action-versioning.md#versioning
+
+Follow these steps to create a new release:
+- create a new release from the Relases page.
+- assign it a tag with semantic version.
+- create or update the major version tag so it points to the latest release:
+```
+git tag -fa v1 -m "Update v1 tag"
+git push origin v1 --force
+```