Initial commit

.github/workflows/publish-features.yml

@@ -0,0 +1,28 @@
+name: Publish features
+on:
+  # push:
+  #   branches: "main"
+  #   paths:
+  #     - src/*/**
+  #     - .github/workflows/publish-features.yml
+  workflow_dispatch:
+concurrency: ${{ github.workflow }}
+jobs:
+  publish-features:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm install -g @devcontainers/cli
+      - uses: docker/login-action@v2
+        with:
+          registry: ghcr.io
+          username: ${{ github.actor }}
+          password: ${{ secrets.GITHUB_TOKEN }}
+      # This just creates a bunch of tarballs and doesn't need the complicated splitting
+      # like feature testing does.
+      - run: devcontainer features publish -r ghcr.io -n ${{ github.repository }} src
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test-features.yml

@@ -0,0 +1,39 @@
+name: Test features
+on:
+  push:
+    branches: "main"
+    paths:
+      - src/*/**
+      - test/*/**
+      - .github/workflows/test-features.yml
+  pull_request:
+    paths:
+      - src/*/**
+      - test/*/**
+      - .github/workflows/test-features.yml
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  list-features:
+    outputs:
+      relevant-features: ${{ steps.list-features.outputs.relevant-features }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - id: list-features
+        uses: devcontainers-community/list-features@v1
+  test-feature:
+    needs: list-features
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(needs.list-features.outputs.relevant-features) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - run: npm install -g @devcontainers/cli
+      - run: devcontainer features test -f ${{ matrix.id }}

.github/workflows/update-feature-readmes.yml

@@ -0,0 +1,42 @@
+name: Update feature readmes
+on:
+  push:
+    branches: "main"
+    paths:
+      - .github/workflows/update-feature-readmes.yml
+      - src/*/devcontainer-feature.json
+  pull_request:
+    paths:
+      - .github/workflows/update-feature-readmes.yml
+      - src/*/devcontainer-feature.json
+  workflow_dispatch:
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  list-features:
+    outputs:
+      changed-features: ${{ steps.list-features-outputs.changed-features }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+        with:
+          fetch-depth: 0
+      - id: list-features
+        uses: devcontainers-community/list-features@v1
+  update-feature-readme:
+    needs: list-features
+    concurrency: ${{ github.ref }}-write
+    permissions:
+      contents: write
+    strategy:
+      fail-fast: false
+      matrix:
+        include: ${{ fromJSON(needs.list-features.outputs.changed-features) }}
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: devcontainers-community/update-feature-readme@v1
+        with:
+          path: src/${{ matrix.id }}
+      - uses: stefanzweifel/git-auto-commit-action@v4

.github/workflows/update-main-readme.yml

@@ -0,0 +1,24 @@
+name: Update main readme
+on:
+  push:
+    branches: "main"
+    paths:
+      - .github/workflows/update-main-readme.yml
+  pull_request:
+    paths:
+      - .github/workflows/update-main-readme.yml
+  registry_package: {}
+  workflow_dispatch: {}
+concurrency:
+  group: ${{ github.workflow }}-${{ github.ref }}
+  cancel-in-progress: true
+jobs:
+  update-main-readme:
+    concurrency: ${{ github.ref }}-write
+    permissions:
+      contents: write
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v3
+      - uses: devcontainers-community/update-features-readme@v1
+      - uses: stefanzweifel/git-auto-commit-action@v4

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2022 Microsoft Corporation
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -0,0 +1,217 @@
+# Dev Container Features: Self Authoring Template
+
+> This repo provides a starting point and example for creating your own custom [dev container Features](https://containers.dev/implementors/features/), hosted for free on GitHub Container Registry.  The example in this repository follows the [dev container Feature distribution specification](https://containers.dev/implementors/features-distribution/).  
+>
+> To provide feedback to the specification, please leave a comment [on spec issue #70](https://github.com/devcontainers/spec/issues/70). For more broad feedback regarding dev container Features, please see [spec issue #61](https://github.com/devcontainers/spec/issues/61).
+
+## Example Contents
+
+This repository contains a _collection_ of two Features - `hello` and `color`. These Features serve as simple feature implementations.  Each sub-section below shows a sample `devcontainer.json` alongside example usage of the Feature.
+
+### `hello`
+
+Running `hello` inside the built container will print the greeting provided to it via its `greeting` option.
+
+```jsonc
+{
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "features": {
+        "ghcr.io/devcontainers/feature-starter/hello:1": {
+            "greeting": "Hello"
+        }
+    }
+}
+```
+
+```bash
+$ hello
+
+Hello, user.
+```
+
+### `color`
+
+Running `color` inside the built container will print your favorite color to standard out.
+
+```jsonc
+{
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "features": {
+        "ghcr.io/devcontainers/feature-starter/color:1": {
+            "favorite": "green"
+        }
+    }
+}
+```
+
+```bash
+$ color
+
+my favorite color is green
+```
+
+## Repo and Feature Structure
+
+Similar to the [`devcontainers/features`](https://github.com/devcontainers/features) repo, this repository has a `src` folder.  Each Feature has its own sub-folder, containing at least a `devcontainer-feature.json` and an entrypoint script `install.sh`. 
+
+```
+├── src
+│   ├── hello
+│   │   ├── devcontainer-feature.json
+│   │   └── install.sh
+│   ├── color
+│   │   ├── devcontainer-feature.json
+│   │   └── install.sh
+|   ├── ...
+│   │   ├── devcontainer-feature.json
+│   │   └── install.sh
+...
+```
+
+An [implementing tool](https://containers.dev/supporting#tools) will composite [the documented dev container properties](https://containers.dev/implementors/features/#devcontainer-feature-json-properties) from the feature's `devcontainer-feature.json` file, and execute in the `install.sh` entrypoint script in the container during build time.  Implementing tools are also free to process attributes under the `customizations` property as desired.
+
+### Options
+
+All available options for a Feature should be declared in the `devcontainer-feature.json`.  The syntax for the `options` property can be found in the [devcontainer Feature json properties reference](https://containers.dev/implementors/features/#devcontainer-feature-json-properties).
+
+For example, the `color` feature provides an enum of three possible options (`red`, `gold`, `green`).  If no option is provided in a user's `devcontainer.json`, the value is set to "red".
+
+```jsonc
+{
+    // ...
+    "options": {
+        "favorite": {
+            "type": "string",
+            "enum": [
+                "red",
+                "gold",
+                "green"
+            ],
+            "default": "red",
+            "description": "Choose your favorite color."
+        }
+    }
+}
+```
+
+Options are exported as Feature-scoped environment variables.  The option name is captialized and sanitized according to [option resolution](https://containers.dev/implementors/features/#option-resolution).
+
+```bash
+#!/bin/bash
+
+echo "Activating feature 'color'"
+echo "The provided favorite color is: ${FAVORITE}"
+
+...
+```
+
+## Distributing Features
+
+### Versioning
+
+Features are individually versioned by the `version` attribute in a Feature's `devcontainer-feature.json`.  Features are versioned according to the semver specification. More details can be found in [the dev container Feature specification](https://containers.dev/implementors/features/#versioning).
+
+### Publishing
+
+> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/features-distribution/).  
+>
+> While any registry [implementing the OCI Distribution spec](https://github.com/opencontainers/distribution-spec) can be used, this template will leverage GHCR (GitHub Container Registry) as the backing registry.
+
+Features are meant to be easily sharable units of dev container configuration and installation code.  
+
+This repo contains a **GitHub Action** [workflow](.github/workflows/release.yaml) that will publish each Feature to GHCR. 
+
+*Allow GitHub Actions to create and approve pull requests* should be enabled in the repository's `Settings > Actions > General > Workflow permissions` for auto generation of `src/<feature>/README.md` per Feature (which merges any existing `src/<feature>/NOTES.md`).
+
+By default, each Feature will be prefixed with the `<owner/<repo>` namespace.  For example, the two Features in this repository can be referenced in a `devcontainer.json` with:
+
+```
+ghcr.io/devcontainers/feature-starter/color:1
+ghcr.io/devcontainers/feature-starter/hello:1
+```
+
+The provided GitHub Action will also publish a third "metadata" package with just the namespace, eg: `ghcr.io/devcontainers/feature-starter`.  This contains information useful for tools aiding in Feature discovery.
+
+'`devcontainers/feature-starter`' is known as the feature collection namespace.
+
+### Adding Features to the Index
+
+If you'd like your Features to appear in our [public index](https://containers.dev/features) so that other community members can find them, you can do the following:
+
+* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io)
+     * This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site
+* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file
+
+This index is from where [supporting tools](https://containers.dev/supporting) like [VS Code Dev Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers) and [GitHub Codespaces](https://github.com/features/codespaces) surface Features for their dev container creation UI.
+
+#### Using private Features in Codespaces
+
+For any Features hosted in GHCR that are kept private, the `GITHUB_TOKEN` access token in your environment will need to have `package:read` and `contents:read` for the associated repository.
+
+Many implementing tools use a broadly scoped access token and will work automatically.  GitHub Codespaces uses repo-scoped tokens, and therefore you'll need to add the permissions in `devcontainer.json`
+
+An example `devcontainer.json` can be found below.
+
+```jsonc
+{
+    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
+    "features": {
+     "ghcr.io/my-org/private-features/hello:1": {
+            "greeting": "Hello"
+        }
+    },
+    "customizations": {
+        "codespaces": {
+            "repositories": {
+                "my-org/private-features": {
+                    "permissions": {
+                        "packages": "read",
+                        "contents": "read"
+                    }
+                }
+            }
+        }
+    }
+}
+```
+
+---
+<!-- REMOVE EVERYTHING THIS LINE AND ABOVE -->
+
+# My awesome Dev Container Features
+
+🤩 My collection of awesome Dev Container Features
+
+<p align=center>
+  <img width=500 src="https://i.imgur.com/7iCBFSC.png">
+</p>
+
+<!-- prettier-ignore-start -->
+<!-- START_FEATURE_LIST -->
+
+<!-- END_FEATURE_LIST -->
+<!-- prettier-ignore-end -->
+
+[↗️ See all features at containers.dev/features]
+
+## Usage
+
+```jsonc
+"features": {
+  "ghcr.io/octocat/my-awesome-features/<feature-id>": {}
+}
+```
+
+## Development
+
+![GitHub Actions](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub+Actions&color=2088FF&logo=GitHub+Actions&logoColor=FFFFFF&label=)
+![Codespaces](https://img.shields.io/static/v1?style=for-the-badge&message=Codespaces&color=181717&logo=GitHub&logoColor=FFFFFF&label=)
+![Devcontainers](https://img.shields.io/static/v1?style=for-the-badge&message=Devcontainers&color=2496ED&logo=Docker&logoColor=FFFFFF&label=)
+
+To test a specific feature, you can use the [devcontainer CLI]:
+
+```sh
+devcontainer features test -f <feature-id>
+```
+
+Someone with appropriate access must manually trigger the <kbd>Publish features</kbd> workflow to create a new release.