Merge branch 'main' into wip-gh-attestations

README.md

@@ -85,8 +85,28 @@ robustness, reliability, and cross-platform compatibility.
 
 ## Getting started
 
-Currently, there is no binary distribution available. To install the tool, you
-must build it from source. To do so, you need to have Rust installed on your
+Currently, weaver can be consumed in one of three ways:
+
+- [Pre-built Binaries](#pre-built-binaries)
+- [Docker Image](#docker-image)
+- [Building from source](#building-from-source)
+
+### Pre-built Binaries
+
+Weaver release attach pre-built binaries for supported platforms with every release.
+Instructions for installing are included in these release notes.
+
+See: [Weaver Releases](https://github.com/open-telemetry/weaver/releases)
+
+### Docker Image
+
+Weaver deploys a docker image for development to [docker hub](https://hub.docker.com/r/otel/weaver).
+
+Instructions for using the docker image can be found [here](docs/docker-guide.md).
+
+### Building from source
+
+To install the tool from source. you need to have Rust installed on your
 system (see [Install Rust](https://www.rust-lang.org/tools/install)).
 
 To build the tool:
@@ -148,13 +168,15 @@ Telemetry Schemas.
   2023 [here](https://docs.google.com/presentation/d/1nxt5VFlC1mUjZ8eecUYK4e4SxThpIVj1IRnIcodMsNI/edit?usp=sharing).
 
 ## Experimental
+
 - [Component Telemetry Schema](docs/component-telemetry-schema.md) (proposal)
 - [Resolved Telemetry Schema](docs/resolved-telemetry-schema.md) (proposal)
 - OpenTelemetry Telemetry Schema
   v1.2.0 [Draft](https://github.com/lquerel/oteps/blob/app-telemetry-schema-format/text/0241-telemetry-schema-ext.md) (
   not yet ready).
 
 ## Links
+
 - [OpenTelemetry Semantic Convention File Format](https://github.com/open-telemetry/build-tools/blob/main/semantic-conventions/syntax.md)
 - [OpenTelemetry Schema File Format v1.1.0](https://opentelemetry.io/docs/specs/otel/schemas/file_format_v1.1.0/)
 - Meta/Facebook's [positional paper](https://research.facebook.com/publications/positional-paper-schema-first-application-telemetry/)

docs/docker-guide.md

@@ -0,0 +1,70 @@
+# How to use Weaver's Docker image
+
+![Docker Image Version](https://img.shields.io/docker/v/otel/weaver?sort=semver&label=Latest%20docker%20image%20version)
+
+Weaver provides a [docker image](https://hub.docker.com/r/otel/weaver) for development purposes.  However, as most docker
+containers being used for Development, some care must be taken in setting up the development environment. This guide
+showcases how to safely leverage the image to leverage the local filesystem without requiring root access.
+
+## Basic Usage - Otel Semconv Codegen
+
+When generating code against the latest OpenTelemetry semantic conventions, we recommend running the docker image as follows:
+
+```sh
+docker run --rm \
+        -u $(id -u ${USER}):$(id -g ${USER}) \
+        --mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
+        --mount 'type=bind,source=$(PWD)/src,target=/home/weaver/target' \
+        otel/weaver:latest \
+        registry generate \
+        --templates=/home/weaver/templates \
+        --target=markdown \
+        /home/weaver/target
+```
+
+This has three key components:
+
+- Using your local user as the docker container user (`-u $(id -u ${USER}):$(id -g ${USER})`)
+- Binding your local codegen templates as readonly (`--mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly'`)
+- Binding the directory where code will be generated to the `/home/weaver/target` directory in the container: (` --mount 'type=bind,source=$(PWD)/src,target=/home/weaver/target'`)
+
+## Advanced Usage - Interactive Shell
+
+Weaver comes with an interactive component which can be leveraged with docker.  Simply run the container with an interactive terminal attached:
+
+```sh
+docker run -it \
+  otel/weaver:latest \
+  registry search
+```
+
+## Advanced Usage - Policies
+
+When enforcing policies or verifying up-to-date documentation with `weaver registry update-markdown --dry-run`, we recommend using readonly mounts within docker:
+
+```sh
+	docker run --rm \
+        -u $(id -u ${USER}):$(id -g ${USER}) \
+        --mount 'type=bind,source=$(PWD)/my-policy-directory,target=/home/weaver/policies,readonly' \
+        --mount 'type=bind,source=$(PWD)/my-schema-yaml-directory,target=/home/weaver/source,readonly' \
+        otel/weaver:latest registry check \
+        --registry=/home/weaver/source \
+        --policy=/home/weaver/policies
+```
+
+or for checking markdown output:
+
+```sh
+docker run --rm \
+        -u $(id -u ${USER}):$(id -g ${USER}) \
+        --mount 'type=bind,source=$(PWD)/templates,target=/home/weaver/templates,readonly' \
+        --mount 'type=bind,source=$(PWD)/my-doc-output,target=/home/weaver/target,readonly' \
+        otel/weaver:latest \
+        registry generate \
+        --templates=/home/weaver/templates \
+        --target=markdown \
+        --dry-run \
+        /home/weaver/target
+```
+
+Notice in both cases, the docker image is mounting local directories as readonly.