Skip to content

Commit 67d2f8d

Browse files
DanielleMaywoodDanielleMaywood
committed
Update README.md and add CONTRIBUTING.md
1 parent 998dfe2 commit 67d2f8d

File tree

2 files changed

+133
-171
lines changed

2 files changed

+133
-171
lines changed

‎CONTRIBUTING.md‎

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# Contributing to Coder's Dev Container Features
2+
3+
This guide contains information about how to contribute to this collection of dev container Features maintained by Coder.
4+
5+
## Current Features
6+
7+
This repository currently contains the following features:
8+
9+
- `code-server` - Adds VS Code in the browser functionality to your dev container
10+
11+
## Adding a New Feature
12+
13+
To add a new feature to this collection:
14+
15+
1. Create a new folder under the `src` directory with the name of your feature
16+
2. Add a `devcontainer-feature.json` file describing your feature and its options
17+
3. Create an `install.sh` script that installs the feature
18+
4. Optionally add a `README.md` with additional documentation
19+
20+
### Feature Structure
21+
22+
Each feature should follow this structure:
23+
24+
```
25+
src/
26+
└── your-feature-name/
27+
├── devcontainer-feature.json # Feature metadata and options
28+
├── install.sh # Installation script
29+
└── README.md # (Optional) Feature-specific documentation
30+
```
31+
32+
### devcontainer-feature.json Example
33+
34+
```json
35+
{
36+
"name": "Your Feature Name",
37+
"id": "your-feature-name",
38+
"version": "1.0.0",
39+
"description": "Brief description of your feature",
40+
"options": {
41+
"optionId": {
42+
"type": "string",
43+
"default": "default value",
44+
"description": "Description of this option"
45+
}
46+
},
47+
"entrypoint": "/usr/local/bin/your-feature-entrypoint",
48+
"dependsOn": {
49+
"ghcr.io/devcontainers/features/common-utils:2": {}
50+
}
51+
}
52+
```
53+
54+
## Testing Your Feature
55+
56+
Before submitting a PR, test your feature by building and using a dev container that incorporates it:
57+
58+
```bash
59+
# From the repository root
60+
cd ..
61+
devcontainer build --workspace-folder ./devcontainer-features --feature-set src/your-feature-name
62+
```
63+
64+
## Versioning Guidelines
65+
66+
Follow semantic versioning for all features:
67+
68+
- Increment the **major** version when making incompatible changes
69+
- Increment the **minor** version when adding functionality in a backward-compatible manner
70+
- Increment the **patch** version when making backward-compatible bug fixes
71+
72+
Update the version in your feature's `devcontainer-feature.json` file.
73+
74+
## Publishing Process
75+
76+
Features in this repository are automatically published to GitHub Container Registry (GHCR) via GitHub Actions when changes are merged to the main branch.
77+
78+
The published features will be available at:
79+
```
80+
ghcr.io/DanielleMaywood/devcontainer-features/feature-id:version
81+
```
82+
83+
For example, the current code-server feature is referenced as:
84+
```
85+
ghcr.io/DanielleMaywood/devcontainer-features/code-server:1
86+
```
87+
88+
### Making Features Public
89+
90+
After a feature is published to GHCR, make it public by:
91+
92+
1. Navigate to the package settings in GHCR:
93+
```
94+
https://github.com/users/DanielleMaywood/packages/container/devcontainer-features%2Fcode-server/settings
95+
```
96+
2. Change the visibility setting to "Public"
97+
98+
## Pull Request Process
99+
100+
1. Fork this repository
101+
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
102+
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
103+
4. Push to the branch (`git push origin feature/amazing-feature`)
104+
5. Open a Pull Request
105+
106+
## Code Style Guidelines
107+
108+
- Use shellcheck to validate your shell scripts
109+
- Include comments explaining complex operations
110+
- Follow the style of existing features for consistency
111+
112+
## Getting Help
113+
114+
If you have questions about contributing to this repository, please open an issue or reach out to DanielleMaywood directly.

‎README.md‎

Lines changed: 19 additions & 171 deletions
Original file line numberDiff line numberDiff line change
@@ -1,188 +1,36 @@
1-
# Dev Container Features: Self Authoring Template
1+
# Dev Container Features Collection
22

3-
> 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/).
4-
>
5-
> 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).
3+
This repository contains a collection of [dev container Features](https://containers.dev/implementors/features/) that can be used to enhance your development environment. The features follow the [dev container Feature distribution specification](https://containers.dev/implementors/features-distribution/) and are hosted for free on GitHub Container Registry.
64

7-
## Example Contents
5+
## Available Features
86

9-
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.
7+
### `code-server`
108

11-
### `hello`
12-
13-
Running `hello` inside the built container will print the greeting provided to it via its `greeting` option.
9+
The `code-server` feature installs [code-server](https://github.com/coder/code-server), which allows you to run VS Code in the browser.
1410

1511
```jsonc
1612
{
1713
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
1814
"features": {
19-
"ghcr.io/devcontainers/feature-starter/hello:1": {
20-
"greeting": "Hello"
15+
"ghcr.io/DanielleMaywood/devcontainer-features/code-server:1": {
16+
"host": "127.0.0.1",
17+
"port": "8080",
18+
"args": "",
19+
"extensions": ""
2120
}
2221
}
2322
}
2423
```
2524

26-
```bash
27-
$ hello
28-
29-
Hello, user.
30-
```
31-
32-
### `color`
33-
34-
Running `color` inside the built container will print your favorite color to standard out.
35-
36-
```jsonc
37-
{
38-
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
39-
"features": {
40-
"ghcr.io/devcontainers/feature-starter/color:1": {
41-
"favorite": "green"
42-
}
43-
}
44-
}
45-
```
46-
47-
```bash
48-
$ color
49-
50-
my favorite color is green
51-
```
52-
53-
## Repo and Feature Structure
54-
55-
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`.
56-
57-
```
58-
├── src
59-
│ ├── hello
60-
│ │ ├── devcontainer-feature.json
61-
│ │ └── install.sh
62-
│ ├── color
63-
│ │ ├── devcontainer-feature.json
64-
│ │ └── install.sh
65-
| ├── ...
66-
│ │ ├── devcontainer-feature.json
67-
│ │ └── install.sh
68-
...
69-
```
70-
71-
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.
72-
73-
### Options
74-
75-
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).
76-
77-
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".
78-
79-
```jsonc
80-
{
81-
// ...
82-
"options": {
83-
"favorite": {
84-
"type": "string",
85-
"enum": [
86-
"red",
87-
"gold",
88-
"green"
89-
],
90-
"default": "red",
91-
"description": "Choose your favorite color."
92-
}
93-
}
94-
}
95-
```
96-
97-
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).
98-
99-
```bash
100-
#!/bin/bash
101-
102-
echo "Activating feature 'color'"
103-
echo "The provided favorite color is: ${FAVORITE}"
104-
105-
...
106-
```
107-
108-
## Distributing Features
109-
110-
### Versioning
111-
112-
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).
113-
114-
### Publishing
25+
#### Options
11526

116-
> NOTE: The Distribution spec can be [found here](https://containers.dev/implementors/features-distribution/).
117-
>
118-
> 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.
27+
| Option | Type | Default | Description |
28+
|--------|------|---------|-------------|
29+
| `host` | string | `127.0.0.1` | The address to bind to when starting code-server |
30+
| `port` | string | `8080` | The port to bind to when starting code-server |
31+
| `args` | string | `""` | Additional arguments to pass to code-server |
32+
| `extensions` | string | `""` | Comma-separated list of VS Code extensions to install |
11933

120-
Features are meant to be easily sharable units of dev container configuration and installation code.
121-
122-
This repo contains a **GitHub Action** [workflow](.github/workflows/release.yaml) that will publish each Feature to GHCR.
123-
124-
*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`).
125-
126-
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:
127-
128-
```
129-
ghcr.io/devcontainers/feature-starter/color:1
130-
ghcr.io/devcontainers/feature-starter/hello:1
131-
```
132-
133-
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.
134-
135-
'`devcontainers/feature-starter`' is known as the feature collection namespace.
136-
137-
### Marking Feature Public
138-
139-
Note that by default, GHCR packages are marked as `private`. To stay within the free tier, Features need to be marked as `public`.
140-
141-
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:
142-
143-
```
144-
https://github.com/users/<owner>/packages/container/<repo>%2F<featureName>/settings
145-
```
34+
## Contributing
14635

147-
<img width="669" alt="image" src="https://user-images.githubusercontent.com/23246594/185244705-232cf86a-bd05-43cb-9c25-07b45b3f4b04.png">
148-
149-
### Adding Features to the Index
150-
151-
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:
152-
153-
* Go to [github.com/devcontainers/devcontainers.github.io](https://github.com/devcontainers/devcontainers.github.io)
154-
* This is the GitHub repo backing the [containers.dev](https://containers.dev/) spec site
155-
* Open a PR to modify the [collection-index.yml](https://github.com/devcontainers/devcontainers.github.io/blob/gh-pages/_data/collection-index.yml) file
156-
157-
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.
158-
159-
#### Using private Features in Codespaces
160-
161-
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.
162-
163-
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`
164-
165-
An example `devcontainer.json` can be found below.
166-
167-
```jsonc
168-
{
169-
"image": "mcr.microsoft.com/devcontainers/base:ubuntu",
170-
"features": {
171-
"ghcr.io/my-org/private-features/hello:1": {
172-
"greeting": "Hello"
173-
}
174-
},
175-
"customizations": {
176-
"codespaces": {
177-
"repositories": {
178-
"my-org/private-features": {
179-
"permissions": {
180-
"packages": "read",
181-
"contents": "read"
182-
}
183-
}
184-
}
185-
}
186-
}
187-
}
188-
```
36+
For information about contributing to this repository, including how to publish features, please see [CONTRIBUTING.md](./CONTRIBUTING.md).

0 commit comments

Comments
 (0)