Skip to content

Commit

Permalink
feat(features): remove demos. add test for latex
Browse files Browse the repository at this point in the history
  • Loading branch information
wohenbushuang committed Apr 3, 2024
1 parent 184ea56 commit bf6302b
Show file tree
Hide file tree
Showing 17 changed files with 37 additions and 479 deletions.
6 changes: 2 additions & 4 deletions .github/workflows/test.yaml
Original file line number Diff line number Diff line change
Expand Up @@ -13,8 +13,7 @@ jobs:
strategy:
matrix:
features:
- color
- hello
- latex
baseImage:
- debian:latest
- ubuntu:latest
Expand All @@ -34,8 +33,7 @@ jobs:
strategy:
matrix:
features:
- color
- hello
- latex
steps:
- uses: actions/checkout@v3

Expand Down
117 changes: 5 additions & 112 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,20 +4,16 @@
>
> 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
### `latex`

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.
Running `latex` inside the built container will install Tex Live latex compiler with tlmgr package manager, alongside LaTeX Workshop extension.

```jsonc
{
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
"features": {
"ghcr.io/devcontainers/feature-starter/hello:1": {
"greeting": "Hello"
"ghcr.io/rnicrosoft-studio/devcontainer-features/latex": {
"scheme": "full" // may take about 30+ minutes
}
}
}
Expand All @@ -29,27 +25,6 @@ $ 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`.
Expand All @@ -59,9 +34,6 @@ Similar to the [`devcontainers/features`](https://github.com/devcontainers/featu
│ ├── hello
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
│ ├── color
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
| ├── ...
│ │ ├── devcontainer-feature.json
│ │ └── install.sh
Expand All @@ -74,37 +46,8 @@ An [implementing tool](https://containers.dev/supporting#tools) will composite [

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
Expand All @@ -123,16 +66,7 @@ This repo contains a **GitHub Action** [workflow](.github/workflows/release.yaml

*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.
By default, each Feature will be prefixed with the `<owner/<repo>` namespace.

### Marking Feature Public

Expand All @@ -145,44 +79,3 @@ https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/setti
```

<img width="669" alt="image" src="https://user-images.githubusercontent.com/23246594/185244705-232cf86a-bd05-43cb-9c25-07b45b3f4b04.png">

### 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"
}
}
}
}
}
}
```
21 changes: 0 additions & 21 deletions src/color/devcontainer-feature.json

This file was deleted.

26 changes: 0 additions & 26 deletions src/color/install.sh

This file was deleted.

22 changes: 0 additions & 22 deletions src/hello/devcontainer-feature.json

This file was deleted.

29 changes: 0 additions & 29 deletions src/hello/install.sh

This file was deleted.

33 changes: 0 additions & 33 deletions test/_global/color_and_hello.sh

This file was deleted.

13 changes: 0 additions & 13 deletions test/_global/scenarios.json

This file was deleted.

17 changes: 0 additions & 17 deletions test/color/gold.sh

This file was deleted.

17 changes: 0 additions & 17 deletions test/color/green.sh

This file was deleted.

Loading

0 comments on commit bf6302b

Please sign in to comment.