[pull] gh-pages from devcontainers:gh-pages

.github/pull_request_template.md

@@ -0,0 +1,35 @@
+<!--
+     📖 Before submitting a Pull Request, please ensure you've read the Contributing Guide: https://containers.dev/implementors/contributing/
+-->
+
+## What type of PR is this?
+
+- [ ] Add a new dev container collection
+- [ ] Update to an existing dev container collection
+- [ ] Documentation/spec update
+- [ ] Other containers.dev site update (UX, layout, etc)
+
+## Related Issues
+
+<!--
+For pull requests that relate or close an issue, please include them
+below. For example: "closes #1234" would connect the current pull
+request to issue 1234. When we merge the pull request, Github will
+automatically close the issue.
+-->
+
+- Related Issue #
+- Closes #
+
+## Description
+
+_Please replace this line with a description of your PR._
+
+### Collection checklist
+_If your PR contributes a new collection, please utilize this checklist:_
+- [ ] Collection name
+- [ ] Maintainer name
+- [ ] Maintainer contact link (i.e. link to a GitHub repo, email)
+- [ ] Repository URL
+- [ ] OCI Reference
+- [ ] I acknowledge that this collection provides new functionality, distinct from the existing collections part of this index.

.github/workflows/publish.yml

@@ -58,7 +58,7 @@ jobs:
           destination: ./_site
 
       - name: Upload artifact
-        uses: actions/upload-pages-artifact@v1
+        uses: actions/upload-pages-artifact@v3
 
   # Deployment job
   deploy:
@@ -70,4 +70,4 @@ jobs:
     steps:
       - name: Deploy to GitHub Pages
         id: deployment
-        uses: actions/deploy-pages@v1
+        uses: actions/deploy-pages@v4

_implementors/contributing.md

@@ -6,19 +6,20 @@ author: Microsoft
 index: 9
 ---
 
-We're excited for your contributions to the Dev Container Specification! This document outlines how you can get involved. 
+We're excited for your contributions to the Dev Container Specification! This document outlines how you can get involved. We also welcome you to join our [community Slack channel](https://aka.ms/dev-container-community).
 
-## <a href="#contribution-approaches" name="contribution-approaches" class="anchor"> Contribution approaches </a>
+## <a href="#contribution-approaches" name="contribution-approaches" class="anchor"> Spec Contribution approaches </a>
 
-- Propose the change via an [issue](https://github.com/devcontainers/spec/issues) in the [spec repo](https://github.com/devcontainers/spec). Try to get early feedback before spending too much effort formalizing it.
-- More formally document the proposed change in terms of properties and their semantics. Look to format your proposal like our [devcontainer.json reference](../json_reference), which is a JSON with Comments (jsonc) format.
+If you'd like to contribute a change or addition to the spec, you may follow the guidance below:
+- Propose the change via an [issue](https://github.com/devcontainers/spec/issues) in this repository. Try to get early feedback before spending too much effort formalizing it.
+- More formally document the proposed change in terms of properties and their semantics. Look to format your proposal like our [devcontainer.json reference](https://aka.ms/devcontainer.json).
 
-Here is a sample proposal:
+Here is a sample:
 
 | Property | Type  | Description |
 |:------------------|:------------|:------------|
 | `image`    | string      | **Required** when using an image. The name of an image in a container registry ([DockerHub](https://hub.docker.com), [GitHub Container Registry](https://docs.github.com/packages/guides/about-github-container-registry), [Azure Container Registry](https://azure.microsoft.com/services/container-registry/)) that VS Code and other `devcontainer.json` supporting services / tools should use to create the dev container. |
-{: .table .table-bordered .table-responsive}
+{: .table .table-bordered}
 
 - PRs to the [schema](https://github.com/microsoft/vscode/blob/main/extensions/configuration-editing/schemas/devContainer.schema.src.json), i.e code or shell scripts demonstrating approaches for implementation.
 
@@ -43,6 +44,20 @@ Tool-specific properties are contained in namespaces in the `"customizations"` p
 
 You may propose adding a new namespace for a specific tool, and any properties specific to that tool.
 
+### <a href="#formatting-guidelines" name="formatting-guidelines" class="anchor"> Formatting Guidelines </a>
+
+When contributing an official doc or referencing dev containers in your projects, please consider the following guidelines:
+
+- Refer to the spec as the "Development Container Specification"
+     - All capital letters
+     - Singular "Container" rather than plural "Containers"
+- The term "dev container" shouldn't be capitalized on its own
+     - It should only be capitalized when referring to an official tool title, like the VS Code Dev Containers extension 
+- Signify `devcontainer.json` is a file type through backticks 
+- Features and Templates should always be capitalized
+- Refer to the CLI as the "Dev Container CLI" (note the caps)
+- Use bolding for emphasis sprinkled throughout sections, rather than try to use it to always bold certain terms
+
 ## <a href="#review-process" name="review-process" class="anchor"> Review process </a>
 
 We use the following [labels](https://github.com/devcontainers/spec/labels) in the spec repo:
@@ -51,3 +66,11 @@ We use the following [labels](https://github.com/devcontainers/spec/labels) in t
 - `finalization`: Proposals we intend to make part of the spec.
 
 [Milestones](https://github.com/devcontainers/spec/milestones) use a "month year" pattern (i.e. January 2022). If a finalized proposal is added to a milestone, it is intended to be merged during that milestone.
+
+## <a href="#community-engagement" name="community-engagement" class="anchor"> Community Engagement </a>
+
+There are several additional options to engage with the dev container community, such as asking questions, providing feedback, or engaging on how your team may use or contribute to dev containers:
+- [GitHub Discussions](https://github.com/devcontainers/spec/discussions): This is a great opportunity to connect with the community and maintainers of this project, without the requirement of contributing a change to the actual spec (which we see more in issues and PRs)
+- [Community Slack channel](https://aka.ms/dev-container-community): This is a great opportunity to connect with the community and maintainers
+- You can always check out the issues and PRs (and contribute new ones) across the repos in the [Dev Containers GitHub org](https://github.com/devcontainers) too!
+- Community collections: You can contribute your own [Templates](https://containers.dev/implementors/templates-distribution/#distribution) and [Features](https://containers.dev/implementors/features-distribution/#distribution) to our [community index](https://containers.dev/collections)!

_implementors/features-distribution.md

@@ -8,7 +8,7 @@ index: 6
 
 **TL;DR Check out the [quick start repository](https://github.com/devcontainers/feature-template) to get started on distributing your own Dev Container Features.**
 
-This specification defines a pattern where community members and organizations can author and self-publish [Dev Container 'Features'](../features). 
+This specification defines a pattern where community members and organizations can author and self-publish [Dev Container Features](../features). 
 
 Goals include:
 
@@ -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:
 
@@ -81,23 +81,23 @@ The `devcontainer-collection.json` is an auto-generated metadata file.
 | :--- | :--- | :--- |
 | `sourceInformation` | object | Metadata from the implementing packaging tool. |
 | `features` | array | The list of features that are contained in this collection.|
-{: .table .table-bordered .table-responsive}
+{: .table .table-bordered}
 
 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 such as the [Dev Container CLI](https://github.com/devcontainers/cli) or [Dev Container Publish GitHub Action](https://github.com/marketplace/actions/dev-container-publish). See the [quick start repository](https://github.com/devcontainers/feature-template) for a full working example.
 
-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.
 
 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 identifier 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.
 
@@ -116,7 +116,7 @@ ARTIFACT_PATH=devcontainer-feature-go.tgz
 for VERSION in 1  1.2  1.2.3  latest
 do
     oras push ${REGISTRY}/${NAMESPACE}/${FEATURE}:${VERSION} \
-            --manifest-config /dev/null:application/vnd.devcontainers \
+            --config /dev/null:application/vnd.devcontainers \
                              ./${ARTIFACT_PATH}:application/vnd.devcontainers.layer.v1+tar
 done
 ```
@@ -131,10 +131,39 @@ REGISTRY=ghcr.io
 NAMESPACE=devcontainers/features
 
 oras push ${REGISTRY}/${NAMESPACE}:latest \
-        --manifest-config /dev/null:application/vnd.devcontainers \
+        --config /dev/null:application/vnd.devcontainers \
                             ./devcontainer-collection.json:application/vnd.devcontainers.collection.layer.v1+json
 ```
 
+Additionally, an [annotation](https://github.com/opencontainers/image-spec/blob/main/annotations.md) named `dev.containers.metadata` should be populated on the manifest when published by an implementing tool.  This annotation is the escaped JSON object of the entire `devcontainer-feature.json` as it appears during the [packaging stage](#packaging).  
+
+An example manifest with the `dev.containers.metadata` annotation:
+
+```json
+{
+  "schemaVersion": 2,
+  "mediaType": "application/vnd.oci.image.manifest.v1+json",
+  "config": {
+    "mediaType": "application/vnd.devcontainers",
+    "digest": "sha256:e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855",
+    "size": 0
+  },
+  "layers": [
+    {
+      "mediaType": "application/vnd.devcontainers.layer.v1+tar",
+      "digest": "sha256:738af5504b253dc6de51d2cb1556cdb7ce70ab18b2f32b0c2f12650ed6d2e4bc",
+      "size": 3584,
+      "annotations": {
+        "org.opencontainers.image.title": "devcontainer-feature-myFeature.tgz"
+      }
+    }
+  ],
+  "annotations": {
+    "dev.containers.metadata": "{\"name\": \"My Feature\",\"id\": \"myFeature\",\"version\": \"1.0.0\",\"dependsOn\": {\"ghcr.io/myotherFeature:1\": {\"flag\": true},\"features.azurecr.io/aThirdFeature:1\": {},\"features.azurecr.io/aFourthFeature:1.2.3\": {}}}"
+  }
+}
+```
+
 ### <a href="#directly-reference-tarball" name="directly-reference-tarball" class="anchor"> Directly referencing a tarball </a>
 
 A Feature can be referenced directly in a user's [`devcontainer.json`](../spec#a-hrefdevcontainerjson-namedevcontainerjson-classanchor-devcontainerjson-a) file by HTTPS URI that points to the tarball from the [package step](#packaging).
@@ -151,7 +180,7 @@ Additional constraints exists when including local Features in a project:
 
 * The project must have a `.devcontainer/` folder at the root of the [**project workspace folder**](/implementors/spec/#project-workspace-folder).
 
-* A local Feature's source code **must** be contained within a sub-folder of the `.devcontainer/ folder`.
+* 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.