Clean up readme (#93)

* Clean up readme

* Remove `lib` directory from repo structure since it no longer exists
* Fix json examples to wrap `"features"` in quotes
* Add some more details about semantic versioning
* Format the markdown file (break long lines into shorter lines, etc)

* Move usage above the repo structure

1 files changed, 74 insertions, 52 deletions

diff --git a/README.md b/README.md
index 7dedd74..43e027b 100644
--- a/README.md
+++ b/README.md
@@ -8,23 +8,72 @@
 </td>
 </tr></table>
 
-'Features' are self-contained units of installation code and development container configuration. Features are designed to install atop a wide-range of base container images (**this repo focuses on `debian` based images**).
+'Features' are self-contained units of installation code and development container configuration. Features are designed
+to install atop a wide-range of base container images (**this repo focuses on `debian` based images**).
 
-Missing a CLI or language in your otherwise _perfect_ container image? Add the relevant 'feature' to the `features` property of a [`devcontainer.json`](https://containers.dev/implementors/json_reference/#general-properties).  A [tool supporting the dev container specification](https://containers.dev/supporting) is required to build a development container.
+Missing a CLI or language in your otherwise _perfect_ container image? Add the relevant 'feature' to the `features`
+property of a [`devcontainer.json`](https://containers.dev/implementors/json_reference/#general-properties). A
+[tool supporting the dev container specification](https://containers.dev/supporting) is required to build a development
+container.
 
-⚠️ Development container 'features' are a [**proposed**](https://github.com/devcontainers/spec/blob/main/proposals/devcontainer-features.md) addition to the [development container specification](https://containers.dev/implementors/spec/). **Please note that 'features' are in preview and subject to breaking changes**.
+⚠️ Development container 'features' are a
+[**proposed**](https://github.com/devcontainers/spec/blob/main/proposals/devcontainer-features.md) addition to the
+[development container specification](https://containers.dev/implementors/spec/). **Please note that 'features' are in
+preview and subject to breaking changes**.
 
-Once the [**proposed**](https://github.com/devcontainers/spec/blob/main/proposals/devcontainer-features.md) specification is accepted, implementation details will be published at [https://containers.dev](https://containers.dev/).
+Once the [**proposed**](https://github.com/devcontainers/spec/blob/main/proposals/devcontainer-features.md)
+specification is accepted, implementation details will be published at
+[https://containers.dev](https://containers.dev/).
 
 
+## Usage
+
+To reference a feature from this repository, add the desired features to a `devcontainer.json`. Each feature has a `README.md` that shows how to reference the feature and which options are available for that feature.
+
+The example below installs the `go` and `docker-in-docker` declared in the [`./src`](./src) directory of this
+repository.
+
+See the relevant feature's README for supported options.
+
+```jsonc
+"name": "my-project-devcontainer",
+"image": "mcr.microsoft.com/devcontainers/base:ubuntu",  // Any generic, debian-based image.
+"features": {
+    "ghcr.io/devcontainers/features/go:1": {
+        "version": "1.18"
+    },
+    "ghcr.io/devcontainers/features/docker-in-docker:1": {
+        "version": "latest",
+        "moby": true
+    }
+}
+```
+
+The `:latest` version annotation is added implicitly if omitted. To pin to a specific package version
+([example](https://github.com/devcontainers/features/pkgs/container/features/go/versions)), append it to the end of the
+feature. Features follow semantic versioning conventions, so you can pin to a major version `:1`, minor version `:1.0`, or patch version `:1.0.0` by specifying the appropriate label.
+
+```jsonc
+"features": {
+    "ghcr.io/devcontainers/features/go:1.0.0": {
+        "version": "1.18"
+    }
+}
+```
+
+The [devcontainer CLI reference implementation](https://github.com/devcontainers/cli) (or a
+[supporting tool](https://containers.dev/supporting)) can be used to build a project's dev container declaring
+'features'.
+
+```bash
+git clone <my-project-with-devcontainer>
+devcontainer build --workspace-folder <path-to-my-project-with-devcontainer>
+```
+
 ## Repo Structure
 
 ```
 .
-├── lib
-|   ├── settings.env
-|   ├── utils.sh
-│   └── ...
 ├── README.md
 ├── src
 │   ├── dotnet
@@ -50,56 +99,29 @@ Once the [**proposed**](https://github.com/devcontainers/spec/blob/main/proposal
 │   └── scenarios.json
 ```
 
-- [`lib`](lib) - A collection of tools, scripts, and shared configuration used generally by this repo's features.
-- [`src`](src) - A collection of subfolders, each declaring a feature. Each subfolder contains at least a `devcontainer-feature.json` and the appropriately declared install script.
-- [`test`](test) - Mirroring `src`, a folder-per-feature with at least a `test.sh` script. The [`devcontainer` CLI](https://github.com/devcontainers/cli) will execute [these tests in CI](https://github.com/devcontainers/features/blob/main/.github/workflows/test-all.yaml).
-- [`test-scenarios`](test-scenarios) - More complex scenarios involving a set of features from this repo. The [`devcontainer` CLI](https://github.com/devcontainers/cli) will execute [these tests in CI](https://github.com/devcontainers/features/blob/main/.github/workflows/test-scenarios.yaml).
+-   [`src`](src) - A collection of subfolders, each declaring a feature. Each subfolder contains at least a
+    `devcontainer-feature.json` and an `install.sh` script.
+-   [`test`](test) - Mirroring `src`, a folder-per-feature with at least a `test.sh` script. The
+    [`devcontainer` CLI](https://github.com/devcontainers/cli) will execute
+    [these tests in CI](https://github.com/devcontainers/features/blob/main/.github/workflows/test-all.yaml).
+-   [`test-scenarios`](test-scenarios) - More complex scenarios involving a set of features from this repo. The
+    [`devcontainer` CLI](https://github.com/devcontainers/cli) will execute
+    [these tests in CI](https://github.com/devcontainers/features/blob/main/.github/workflows/test-scenarios.yaml).
 
-## Usage
-
-To reference a feature from this repository, add the desired features to a `devcontainer.json`.
-
-The example below installs the `go` and `docker-in-docker` declared in the [`./src`](./src) directory of this repository.
-
-See the relevant feature's README for supported options.
-
-```jsonc
-"name": "my-project-devcontainer",
-"image": "mcr.microsoft.com/devcontainers/base:ubuntu",  // Any generic, debian-based image.
-features: {
-    "ghcr.io/devcontainers/features/go:1": {
-        "version": "1.18"
-    },
-    "ghcr.io/devcontainers/features/docker-in-docker:1": {
-        "version": "latest",
-        "moby": true
-    }
-}
-```
-
-The `:latest` version annotation is added implicitly if omitted. To pin to a specific package version ([example](https://github.com/devcontainers/features/pkgs/container/features/go/versions)), append it to the end of the feature.
-
-```jsonc
-features: {
-    "ghcr.io/devcontainers/features/go:1": {
-        "version": "1.18"
-    },
-```
-
-The [devcontainer CLI reference implementation](https://github.com/devcontainers/cli) (or a [supporting tool](https://containers.dev/supporting)) can be used to build a project's dev container declaring 'features'.
-
-```bash
-git clone <my-project-with-devcontainer>
-devcontainer build --workspace-folder <path-to-my-project-with-devcontainer>
-```
 ## Contributions
 
 ### Creating your own collection of features
 
-Please see the [proposed specification](https://github.com/devcontainers/spec/blob/main/proposals/devcontainer-features-distribution.md) on how to start to author and distribute features your own features.
+Please see the
+[proposed specification](https://github.com/devcontainers/spec/blob/main/proposals/devcontainer-features-distribution.md)
+on how to start to author and distribute features your own features.
 
-We're excited for you to create features!  Our team is actively iterating on tools and examples to help members of the community author their own dev container features. If you have any feedback along the way, please let us know in the specification repo's issues on [features](https://github.com/devcontainers/spec/issues/61) or [feature distribution](https://github.com/devcontainers/spec/issues/70).
+We're excited for you to create features! Our team is actively iterating on tools and examples to help members of the
+community author their own dev container features. If you have any feedback along the way, please let us know in the
+specification repo's issues on [features](https://github.com/devcontainers/spec/issues/61) or
+[feature distribution](https://github.com/devcontainers/spec/issues/70).
 
 ### Contributing to this repository
 
-This repository will accept improvement and bug fix contributions related to the [current set of maintained features](./src).  
+This repository will accept improvement and bug fix contributions related to the
+[current set of maintained features](./src).