Skip to content

Latest commit

 

History

History
67 lines (47 loc) · 4.36 KB

contributing.md

File metadata and controls

67 lines (47 loc) · 4.36 KB
Raw

How to Contribute to the Dev Container Specification

We're excited for your contributions to the dev container specification! This document outlines how you can get involved.

Contribution approaches

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 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, which is a JSON with Comments (jsonc) format.

Here is a sample:

Property Type Description
image string Required when using an image. The name of an image in a container registry (DockerHub, GitHub Container Registry, Azure Container Registry) that VS Code and other devcontainer.json supporting services / tools should use to create the dev container.
  • PRs to the schema, i.e code or shell scripts demonstrating approaches for implementation.

Once there is discussion on your proposal, please also open and link a PR to update the devcontainer.json reference doc. When your proposal is merged, the docs will be kept up-to-date with the latest spec.

Contributing tool-specific support

Tool-specific properties are contained in namespaces in the "customizations" property. For instance, VS Code specific properties are formatted as:

// Configure tool-specific properties.
"customizations": {
     // Configure properties specific to VS Code.
     "vscode": {
          // Set *default* container specific settings.json values on container create.
          "settings": {},
			
          // Additional VS Code specific properties...
     }
},

You may propose adding a new namespace for a specific tool, and any properties specific to that tool.

Formatting Guidelines

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

Review process

We use the following labels:

  • proposal: Issues under discussion, still collecting feedback.
  • finalization: Proposals we intend to make part of the 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.

Community Engagement

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: 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: 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 too!