From 8c287517b92b4f0cf2bdcdc3399fbed758c6439e Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Wed, 31 May 2023 14:04:35 -0500 Subject: [PATCH 1/7] wip: add readme header placeholder --- README.md | 186 +++--------------------------------------------------- 1 file changed, 10 insertions(+), 176 deletions(-) diff --git a/README.md b/README.md index ffadd7f..7c8f937 100644 --- a/README.md +++ b/README.md @@ -1,186 +1,20 @@ ![๐Ÿšง Under construction ๐Ÿ‘ทโ€โ™‚๏ธ](https://i.imgur.com/LEP2R3N.png) -# Dev Container Features: Self Authoring Template +# Devcontainer community features -> 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). +๐Ÿงฐ Community-driven collection of addons for [@devcontainers] -## 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. +![](https://picsum.photos/600/400) -### `hello` +[Docs website](https://devcontainers-community.github.io/features/) +| [Official feature index](https://containers.dev/features) -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" - } - } -} -``` +## Usage -```bash -$ hello +To get started with a devcontainer feature... -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. By default, each Feature will be prefixed with the `` 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. - -### Marking Feature Public - -Note that by default, GHCR packages are marked as `private`. To stay within the free tier, Features need to be marked as `public`. - -This can be done by navigating to the Feature's "package settings" page in GHCR, and setting the visibility to 'public`. The URL may look something like: - -``` -https://github.com/users//packages/container/%2F/settings -``` - -image - -### 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" - } - } - } - } - } -} -``` +[@devcontainers]: https://github.com/devcontainers From 9380ad343b7f2cf3ebfbed51cce47077f52facf9 Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 6 Jun 2023 01:04:09 -0500 Subject: [PATCH 2/7] Add usage section --- README.md | 29 +++++++++++++++++++++++++++-- 1 file changed, 27 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index 7c8f937..c717caa 100644 --- a/README.md +++ b/README.md @@ -6,15 +6,40 @@
-![](https://picsum.photos/600/400) +![](https://i.imgur.com/Gz9yWx8.png) [Docs website](https://devcontainers-community.github.io/features/) | [Official feature index](https://containers.dev/features)
+โž• Add extra features to your GitHub Codespace \ +๐Ÿณ Use JSON, not `Dockerfile`s! \ +๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ Community-driven maintainership + ## Usage -To get started with a devcontainer feature... +![JSON](https://img.shields.io/static/v1?style=for-the-badge&message=JSON&color=000000&logo=JSON&logoColor=FFFFFF&label=) +![GitHub Codespaces](https://img.shields.io/static/v1?style=for-the-badge&message=GitHub+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=) + +Add a `features: {}` key to your existing `devcontainer.json` file, or make a +new one at `.devcontainer/devcontainer.json` in your repository. Then, just add +[one of the features that we offer] to the object map with an optional `{}` +options object. + +```jsonc +// .devcontainer/devcontainer.json +{ + "features": { + "ghcr.io/devcontainers-community/features/dart": {} + } +} +``` + +[๐Ÿ“š Read more about each feature on our documentation website!](https://devcontainers-community.github.io/features/) + [@devcontainers]: https://github.com/devcontainers +[one of the features that we offer]: https://devcontainers-community.github.io/features/ + From 134b1f3bef3842ee461a11a689c72a5df93a3337 Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 6 Jun 2023 01:12:23 -0500 Subject: [PATCH 3/7] Add development section --- README.md | 33 +++++++++++++++++++++++++++++++++ 1 file changed, 33 insertions(+) diff --git a/README.md b/README.md index c717caa..99822ee 100644 --- a/README.md +++ b/README.md @@ -17,6 +17,11 @@ ๐Ÿณ Use JSON, not `Dockerfile`s! \ ๐Ÿ‘จโ€๐Ÿ‘ฉโ€๐Ÿ‘งโ€๐Ÿ‘ฆ Community-driven maintainership +**๐Ÿค We want you!** If you're a community devcontainer feature maintainer, we'd +love to add you to this project! โค๏ธ If you just want to hand off a devcontainer +feature that you no longer want to maintain, **that's perfect too**. Open a +[Discussion] and let's have a friendly chat. ๐Ÿ˜Š + ## Usage ![JSON](https://img.shields.io/static/v1?style=for-the-badge&message=JSON&color=000000&logo=JSON&logoColor=FFFFFF&label=) @@ -39,7 +44,35 @@ options object. [๐Ÿ“š Read more about each feature on our documentation website!](https://devcontainers-community.github.io/features/) +## Development + +![Devcontainers](https://img.shields.io/static/v1?style=for-the-badge&message=Devcontainers&color=2496ED&logo=Docker&logoColor=FFFFFF&label=) +![Bash](https://img.shields.io/static/v1?style=for-the-badge&message=Bash&color=4EAA25&logo=GNU+Bash&logoColor=FFFFFF&label=) + +๐Ÿฃ The @devcontainers-community organization is still in its early stages. This +features repository is currently trying to **hit the highlights first**. That +means popular features first! If you notice a bug ๐Ÿ› or have an improvement +suggestion ๐Ÿ’ก we'd love to hear it! ๐Ÿ˜ + +If you're interested in getting started modifying, adding, or testing a template +in this repository, you can do so without even leaving your browser thanks to +GitHub Codespaces! โ˜๏ธ After optionally forking the repository, you just hit the +green Code button at the top of the GitHub web UI and then Create codespace on +main. ๐Ÿš€ + +After launching your dev environment and making some changes, you're probably +going to want to test those changes. Run the `devcontainer features test` +command to run _all_ the tests, or just `-f` to run a specific one that you're +working on. Be warned that this involves some heavyweight Docker-ing around! + +```sh +devcontainer features test +``` + +๐Ÿค Check out our contributing guide to see how to get your changes merged! + [@devcontainers]: https://github.com/devcontainers [one of the features that we offer]: https://devcontainers-community.github.io/features/ +[Discussion]: https://github.com/devcontainers-community/features/discussions/new?category=general From 7fa16b51423b8e22ea7bffee993545a92c11e825 Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 13 Jun 2023 01:04:22 +0000 Subject: [PATCH 4/7] line ending --- README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/README.md b/README.md index c823d25..99822ee 100644 --- a/README.md +++ b/README.md @@ -75,4 +75,4 @@ devcontainer features test [@devcontainers]: https://github.com/devcontainers [one of the features that we offer]: https://devcontainers-community.github.io/features/ [Discussion]: https://github.com/devcontainers-community/features/discussions/new?category=general - \ No newline at end of file + From 1253f8573b0036231f7bf1144b22417e8691386a Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 13 Jun 2023 01:04:43 +0000 Subject: [PATCH 5/7] Remove under construction banner --- README.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/README.md b/README.md index 99822ee..d55ee77 100644 --- a/README.md +++ b/README.md @@ -1,5 +1,3 @@ -![๐Ÿšง Under construction ๐Ÿ‘ทโ€โ™‚๏ธ](https://i.imgur.com/LEP2R3N.png) - # Devcontainer community features ๐Ÿงฐ Community-driven collection of addons for [@devcontainers] From 93476946db53787263423bf6d0033b12b3a1bffd Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 13 Jun 2023 01:06:15 +0000 Subject: [PATCH 6/7] add back construction header with lint disable rules --- README.md | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/README.md b/README.md index d55ee77..c2c6c69 100644 --- a/README.md +++ b/README.md @@ -1,3 +1,7 @@ + + +![๐Ÿšง Under construction ๐Ÿ‘ทโ€โ™‚๏ธ](https://i.imgur.com/LEP2R3N.png) + # Devcontainer community features ๐Ÿงฐ Community-driven collection of addons for [@devcontainers] From 49674cd3d4d706d1bdeb6c5faf6d8694138000b7 Mon Sep 17 00:00:00 2001 From: Jacob Hummer Date: Tue, 13 Jun 2023 01:10:20 +0000 Subject: [PATCH 7/7] Add alt text to header image --- README.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/README.md b/README.md index c2c6c69..1d2be17 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ - + ![๐Ÿšง Under construction ๐Ÿ‘ทโ€โ™‚๏ธ](https://i.imgur.com/LEP2R3N.png) @@ -8,7 +8,7 @@
-![](https://i.imgur.com/Gz9yWx8.png) +![Code demo](https://i.imgur.com/Gz9yWx8.png) [Docs website](https://devcontainers-community.github.io/features/) | [Official feature index](https://containers.dev/features)