Updates to Features content (#28)

* Update features-distribution.md

* Update features.md

Author: bamurtaugh

_implementors/features-distribution.md

@@ -23,7 +23,7 @@ Goals include:
 
 Features source code is stored in a git repository.
 
-For ease of authorship and maintenance, [1..n] features can share a single git repository. This set of features is referred to as a "collection," and will share the same [`devcontainer-collection.json`](#devcontainer-collection.json) file and "namespace" (eg. `<owner>/<repo>`).
+For ease of authorship and maintenance, [1..n] features can share a single git repository. This set of Features is referred to as a "collection," and will share the same [`devcontainer-collection.json`](#devcontainer-collection.json) file and "namespace" (eg. `<owner>/<repo>`).
 
 Source code for the set follows the example file structure below:
 
@@ -53,25 +53,25 @@ Source code for the set follows the example file structure below:
 ├── ...
 ```
 
-... where `src` is a directory containing a sub-folder with the name of the feature (e.g. `src/dotnet` or `src/go`) with at least a file named `devcontainer-feature.json` that contains the feature metadata, and an `install.sh` script that implementing tools will use as the entrypoint to install the feature.
+... where `src` is a directory containing a sub-folder with the name of the Feature (e.g. `src/dotnet` or `src/go`) with at least a file named `devcontainer-feature.json` that contains the Feature metadata, and an `install.sh` script that implementing tools will use as the entrypoint to install the Feature.
 
-Each sub-directory should be named such that it matches the `id` field of the `devcontainer-feature.json`.  Other files can also be included in the feature's sub-directory, and will be included during the [packaging step](#packaging) alongside the two required files.  Any files that are not part of the feature's sub-directory (e.g. outside of `src/dotnet`) will not included in the [packaging step](#packaging).
+Each sub-directory should be named such that it matches the `id` field of the `devcontainer-feature.json`.  Other files can also be included in the Feature's sub-directory, and will be included during the [packaging step](#packaging) alongside the two required files.  Any files that are not part of the Feature's sub-directory (e.g. outside of `src/dotnet`) will not included in the [packaging step](#packaging).
 
-Optionally, a mirrored `test` directory can be included with an accompanying `test.sh` script.  Implementing tools may use this to run tests against the given feature.
+Optionally, a mirrored `test` directory can be included with an accompanying `test.sh` script.  Implementing tools may use this to run tests against the given Feature.
 
 ## <a href="#versioning" name="versioning" class="anchor"> Versioning </a>
 
-Each feature is individually [versioned according to the semver specification](https://semver.org/).  The `version` property in the respective `devcontainer-feature.json` file is parsed to determine if the feature should be republished.
+Each Feature is individually [versioned according to the semver specification](https://semver.org/).  The `version` property in the respective `devcontainer-feature.json` file is parsed to determine if the Feature should be republished.
 
-Tooling that handles publishing features will not republish features if that exact version has already been published; however, tooling must republish major and minor versions in accordance with the semver specification.
+Tooling that handles publishing Features will not republish Features if that exact version has already been published; however, tooling must republish major and minor versions in accordance with the semver specification.
 
 ## <a href="#packaging" name="packaging" class="anchor"> Packaging </a>
 
-Features are distributed as tarballs.  The tarball contains the entire contents of the feature sub-directory, including the `devcontainer-feature.json`, `install.sh`, and any other files in the directory.
+Features are distributed as tarballs. The tarball contains the entire contents of the Feature sub-directory, including the `devcontainer-feature.json`, `install.sh`, and any other files in the directory.
 
-The tarball is named `devcontainer-feature-<id>.tgz`, where `<id>` is the feature's `id` field.
+The tarball is named `devcontainer-feature-<id>.tgz`, where `<id>` is the Feature's `id` field.
 
-A reference implementation for packaging and distributing features is provided as a GitHub Action (https://github.com/devcontainers/action).
+A reference implementation for packaging and distributing Features is provided as a GitHub Action (https://github.com/devcontainers/action).
 
 ### <a href="#devcontainer-collection-json" name="devcontainer-collection-json" class="anchor"> devcontainer-collection.json </a>
 
@@ -83,25 +83,25 @@ The `devcontainer-collection.json` is an auto-generated metadata file.
 | `features` | array | The list of features that are contained in this collection.|
 {: .table .table-bordered .table-responsive}
 
-Each features's `devcontainer-feature.json` metadata file is appended into the `features` top-level array.
+Each Features's `devcontainer-feature.json` metadata file is appended into the `features` top-level array.
 
 ## <a href="#distribution" name="distribution" class="anchor"> Distribution </a>
 
-There are several supported ways to distribute features.  Distribution is handled by the implementing packaging tool.
+There are several supported ways to distribute Features.  Distribution is handled by the implementing packaging tool.
 
-A user references a distributed feature in a `devcontainer.json` as defined in ['referencing a feature'](../features#referencing-a-feature).
+A user references a distributed Feature in a `devcontainer.json` as defined in ['referencing a feature'](../features#referencing-a-feature).
 
 ### <a href="#oci-registry" name="oci-registry" class="anchor"> OCI Registry </a>
 
-An OCI registry that implements the [OCI Artifact Distribution Specification](https://github.com/opencontainers/distribution-spec) serves as the primary distribution mechanism for features.
+An OCI registry that implements the [OCI Artifact Distribution Specification](https://github.com/opencontainers/distribution-spec) serves as the primary distribution mechanism for Features.
 
-Each packaged feature is pushed to the registry following the naming convention `<registry>/<namespace>/<id>[:version]`, where version is the major, minor, and patch version of the feature, according to the semver specification.
+Each packaged Feature is pushed to the registry following the naming convention `<registry>/<namespace>/<id>[:version]`, where version is the major, minor, and patch version of the Feature, according to the semver specification.
 
-> **Note:** The `namespace` is a unique indentifier for the collection of features.  There are no strict rules for the `namespace`; however, one pattern is to set `namespace` equal to source repository's `<owner>/<repo>`. 
+> **Note:** The `namespace` is a unique indentifier for the collection of Features.  There are no strict rules for the `namespace`; however, one pattern is to set `namespace` equal to source repository's `<owner>/<repo>`. 
 
 A custom media type `application/vnd.devcontainers` and `application/vnd.devcontainers.layer.v1+tar` are used as demonstrated below.
 
-For example, the `go` feature in the `devcontainers/features` namespace at version `1.2.3` would be pushed to the ghcr.io OCI registry.  
+For example, the `go` Feature in the `devcontainers/features` namespace at version `1.2.3` would be pushed to the ghcr.io OCI registry.  
 
 > **Note:** The example below uses [`oras`](https://oras.land/) for demonstration purposes.  A supporting tool should directly implement the required functionality from the aforementioned OCI artifact distribution specification.
 
@@ -121,7 +121,7 @@ do
 done
 ```
 
-The "namespace" is the globally identifiable name for the collection of features. (eg: `owner/repo` for the source code's git repository).
+The "namespace" is the globally identifiable name for the collection of Features. (eg: `owner/repo` for the source code's git repository).
 
 The auto-generated `devcontainer-collection.json` is pushed to the registry with the same `namespace` as above and no accompanying `feature` name. The collection file is always tagged as `latest`.
 
@@ -143,15 +143,23 @@ The `.tgz` archive file must be named `devcontainer-feature-<featureId>.tgz`.
 
 ### <a href="#addendum-locally-referenced" name="addendum-locally-referenced" class="anchor"> Locally referenced Features </a>
 
-To aid in feature authorship, or in instances where a feature should not be published externally, individual features can be referenced locally from the project's file tree.
+Instead of publishing a Feature to an OCI registry, a Feature's source code may be referenced from a local folder. Locally referencing a Feature may be useful when first authoring a Feature.
 
-A local feature is placed in a `.devcontainer/` folder at the root of the [**project workspace folder**](../spec#a-hrefproject-workspace-folder-classanchor-project-workspace-folder-a) and referenced in a user's [`.devcontainer/devcontainer.json`](../spec#a-hrefdevcontainerjson-namedevcontainerjson-classanchor-devcontainerjson-a) by relative path.
+A local Feature is referenced in the devcontainer's `feature` object **relative to the folder containing the project's `devcontainer.json`**.
 
-The relative path is provided using unix-style path syntax (eg `./<...>`), regardless of the host operating system.
+Additional constraints exists when including local Features in a project:
 
-A local feature may **not** be referenced by absolute path, or by a path outside the `.devcontainer/` folder. 
+* The project must have a `.devcontainer/` folder at the root of the [**project workspace folder**](/docs/specs/devcontainer-reference.md#project-workspace-folder).
 
-The provided relative path is a path to the folder containing at least a `devcontainer-feature.json` and `install.sh` file, mirroring the structure [previously outlined](#Source-Code).
+* A local Feature's source code **must** be contained within a sub-folder of the `.devcontainer/ folder`.
+
+* The sub-folder name **must** match the Feature's `id` field.
+
+* A local Feature may **not** be referenced by absolute path.
+
+* The local Feature's sub-folder **must** contain at least a `devcontainer-feature.json` file and `install.sh` entrypoint script, mirroring the [previously outlined file structure](#Source-code).
+
+The relative path is provided using unix-style path syntax (eg `./myFeature`) regardless of the host operating system.
 
 An example project is illustrated below:
 
@@ -178,4 +186,4 @@ An example project is illustrated below:
                 "./localFeatureB": {}
         }
 }
-```
+```