Move proposals and add documentation (devcontainers#339)

bamurtaugh · bamurtaugh · web-flow · commit 638a8e05e34e · 2023-11-14T16:58:14.000-08:00
* Move finalized proposals

* Update specs and readmes

* Polish

---------

Co-authored-by: bamurtaugh &lt;brmurtau@microsoft.com&gt;
diff --git a/README.md b/README.md
@@ -20,7 +20,7 @@ A GitHub Action and an Azure DevOps Task are available in [devcontainers/ci](htt
 
 You may review the specification in the [docs/specs folder](https://github.com/devcontainers/spec/tree/main/docs/specs) of this repo.
 
-You may also review proposed references in the [proposals folder](https://github.com/devcontainers/spec/tree/main/proposals).
+You may also review active proposals in the [proposals folder](https://github.com/devcontainers/spec/tree/main/proposals).
 
 Images used in this repo will be contained in the [images folder](/images). The icon for the [dev container GitHub org](https://github.com/devcontainers) is from the [Fluent icon library](https://github.com/microsoft/fluentui-system-icons/blob/master/assets/Cube/SVG/ic_fluent_cube_32_filled.svg).
 
diff --git a/docs/README.md b/docs/README.md
@@ -1,3 +1,19 @@
-# Documentation
+# Specification Documentation
 
-Documentation and reference material about development containers and the dev container CLI.
+The files in this folder detail the Dev Container Specification.
+
+We add any proposal to the [**proposals folder**](https://github.com/devcontainers/spec/tree/main/proposals), only if the proposal is accepted. It stays in that folder until the implementation is in progress. Once code/schema changes are released, we move it into the [**specs folder**](https://github.com/devcontainers/spec/tree/main/docs/specs).
+
+> **Note:** Our [contributing.md](/contributing.md) documents guidelines on contributing to the spec, as well as labels (proposal and finalization) defined for this process for GitHub issues.
+
+There are several main specs in this folder, outlining the key top-level behavior of dev containers, Templates, and Features:
+
+* [Main dev container spec](/docs/specs/devcontainer-reference.md)
+* [Dev container metadata reference](/docs/specs/devcontainerjson-reference.md)
+* [Main Templates spec](/docs/specs/devcontainer-templates.md)
+* [Templates distribution spec](/docs/specs/devcontainer-templates-distribution.md)
+* [Main Features spec](/docs/specs/devcontainer-features.md)
+* [Features distribution spec](/docs/specs/devcontainer-features-distribution.md)
+* [Tools that support the spec](/docs/specs/supporting-tools.md)
+
+The remainder of the files in this folder outline specifications for specific dev container behaviors. Each file includes links to when the proposal was first discussed and when it was merged into the Dev Container CLI or schema.
diff --git a/docs/specs/declarative-secrets.md b/docs/specs/declarative-secrets.md
@@ -1,6 +1,12 @@
 # Declarative Secrets
 
-## Motiviation
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/198, https://github.com/devcontainers/spec/issues/216
+* Schema PR: https://github.com/devcontainers/spec/pull/303
+
+Below is the original proposal.
+
+## Motivation
 
 Various projects exist in the wild that require various secrets for them to run properly. Examples include:
 
diff --git a/docs/specs/devcontainer-id-variable.md b/docs/specs/devcontainer-id-variable.md
@@ -1,3 +1,11 @@
+# Dev Container ID
+
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/62
+* CLI PR: https://github.com/devcontainers/cli/pull/242
+
+Below is the original proposal.
+
 ## Goal
 
 Allow features to refer to an identifier that is unique to the dev container they are installed into and that is stable across rebuilds.
diff --git a/docs/specs/devcontainer-lockfile.md b/docs/specs/devcontainer-lockfile.md
@@ -1,3 +1,11 @@
+# Lockfiles
+
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/236
+* CLI PR: https://github.com/devcontainers/cli/issues/564
+
+Below is the original proposal.
+
 ## Goal
 
 Introduce a lockfile that records the exact version, download information and checksums for each feature listed in the devcontainer.json.
diff --git a/docs/specs/devcontainer-reference.md b/docs/specs/devcontainer-reference.md
@@ -1,4 +1,4 @@
-# Dev container specification
+# Dev Container Specification
 
 The purpose of the **Development Container Specification** is to provide a way to enrich containers with the content and metadata necessary to enable development inside them. These container **environments** should be easy to use, create, and recreate. 
 
diff --git a/docs/specs/devcontainerjson-reference.md b/docs/specs/devcontainerjson-reference.md
@@ -1,4 +1,4 @@
-# Dev Container metadata reference
+# Dev Container Metadata Reference
 
 The `devcontainer.json` file contains any needed metadata and settings required to configurate a **development container** for a given well-defined tool and runtime stack. It can be used by [tools and services that support the dev container spec](supporting-tools.md) to create a **development environment** that contains one or more **development containers**.
 
diff --git a/docs/specs/feature-dependencies.md b/docs/specs/feature-dependencies.md
@@ -1,8 +1,10 @@
 # Feature Dependencies
 
-Reference: https://github.com/devcontainers/spec/issues/109
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/109
+* CLI PR: https://github.com/devcontainers/cli/commit/236b85162a945a1af9e72fcbe02eb5c7c864b31d
 
-**NOTE**: A reference implementation was introduced in https://github.com/devcontainers/cli/commit/236b85162a945a1af9e72fcbe02eb5c7c864b31d
+Below is the original proposal.
 
 ## Motivation
 
diff --git a/docs/specs/features-contribute-lifecycle-scripts.md b/docs/specs/features-contribute-lifecycle-scripts.md
@@ -1,6 +1,10 @@
-# [Proposal] Allow Dev Container Features to contribute lifecycle scripts
+# Allow Dev Container Features to contribute lifecycle scripts
 
-Related to: https://github.com/devcontainers/spec/issues/60, https://github.com/devcontainers/spec/issues/181
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/60, https://github.com/devcontainers/spec/issues/181
+* CLI PR: https://github.com/devcontainers/cli/pull/390
+
+Below is the original proposal.
 
 ## Goal
 
diff --git a/docs/specs/features-legacyIds-deprecated-properties.md b/docs/specs/features-legacyIds-deprecated-properties.md
@@ -1,21 +1,31 @@
-Goal: Adds support for renaming and deprecating a Feature.
+# Renaming and Deprecating Features
+
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/146
+* CLI PR: https://github.com/devcontainers/cli/pull/346, https://github.com/devcontainers/cli/pull/335
+
+Below is the original proposal.
+
+## Goal
+
+Adds support for renaming and deprecating a Feature.
 
 Adding two new properties to the [devcontainer-feature.json](../docs/specs/devcontainer-features.md#devcontainer-featurejson-properties) 👇 
 
-# 1. legacyIds
+## 1. legacyIds
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
 | `legacyIds` | array | Defaults to `[]`. Array of old IDs used to publish this Feature. The property is useful for renaming a currently published Feature within a single namespace. |
 
-## Steps to rename a Feature
+### Steps to rename a Feature
 
 1. Update the Feature [source code](../docs/specs/features-distribution/#source-code) folder and the `id` property in the [devcontainer-feature.json properties](../docs/specs/devcontainer-features.md#devcontainer-featurejson-properties) to reflect the new `id`. Other properties (`name`, `documentationUrl`, etc.) can optionally be updated during this step.
 2. Add or update the `legacyIds` property to the Feature, including the previously used `id`.
 3. Bump the semantic version of the Feature.  
 4. Rerun the `devcontainer features publish` command, or equivalent tool that implements the [Features distribution specification](../docs/specs/features-distribution/#distribution).
 
-### Example: Renaming a Feature
+#### Example: Renaming a Feature
 
 Let's say we currently have a `docker-from-docker` Feature 👇 
 
@@ -48,24 +58,24 @@ We'd want to rename this Feature to `docker-outside-of-docker`. The source code
 
 **Note** - The semantic version of the Feature defined by the `version` property should be **continued** and should not be restarted at `1.0.0`.
 
-### Changes to the Features distribution specification
+#### Changes to the Features distribution specification
 
 - [Tools implementing the Dev Container Features Distribution Specification](../docs/specs/features-distribution/#distribution) (eg: [Dev Container CLI](https://github.com/devcontainers/cli) and [Dev Container Publish GitHub Action](https://github.com/marketplace/actions/dev-container-publish)) will dual publish the old `id`s (defined by the `legacyIds` property), and the new `id`.
   - The [putManifestWithTags](https://github.com/devcontainers/cli/blob/main/src/spec-configuration/containerCollectionsOCIPush.ts#L172) will be modified. The same `tgz` file for the `id` will be pushed to the `id`s  mentioned by the `legacyIds` property for all the [tags](https://github.com/devcontainers/cli/blob/main/src/spec-configuration/containerCollectionsOCIPush.ts#L175).
 
-### Supporting backwards compatibility for [`installsAfter`](../docs/specs/devcontainer-features.md#2-the-installsafter-feature-property) property
+#### Supporting backwards compatibility for [`installsAfter`](../docs/specs/devcontainer-features.md#2-the-installsafter-feature-property) property
 
 - Currently the `installsAfter` property is defined as an array consisting of the Feature `id` that should be installed before the given Feature.
 - The Feature to be renamed could be already defined by other Feature authors in their `installsAfter` property. Renaming the `id` could change the installation order for them if the `installsAfter` property is not updated with the new `id`. In order to avoid this unexpected behavior and to support back compat, the CLI tooling will be updated to also look at the `legacyIds` property along with the `id` for determining the installation order.
  
- ### Supporting tools
+ #### Supporting tools
  
 This property can be used by the supporting tools to indicate Feature rename in few ways 
  - [Dev Container Publish GitHub Action](https://github.com/devcontainers/action) which auto-generates the README files can add a note with a list of old `id`s which were used to publish this Feature.
  -  In the scenarios where Dev Configs are referencing the old `id`s,  the VS Code extension hints could be enhanced to deliver this warning that the `id` was renamed to a new one.
 - The [containers.dev/features](https://containers.dev/features) website, and [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) wouldn't list the old `id`, instead list the new `id` of Features.
  
-# 2. deprecated
+## 2. deprecated
 
 | Property | Type | Description |
 | :--- | :--- | :--- |
diff --git a/docs/specs/features-user-env-variables.md b/docs/specs/features-user-env-variables.md
@@ -1,3 +1,11 @@
+# User Env Variables for Features
+
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/91
+* CLI PR: https://github.com/devcontainers/cli/pull/228
+
+Below is the original proposal.
+
 ## Goal
 
 Feature scripts run as the `root` user and sometimes need to know which user account the dev container will be used with.
diff --git a/docs/specs/gpu-host-requirement.md b/docs/specs/gpu-host-requirement.md
@@ -1,4 +1,10 @@
-# GPU host requirement
+# GPU Host Requirement
+
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/82
+* CLI PR: https://github.com/devcontainers/cli/pull/173
+
+Below is the original proposal.
 
 ## Goal
 
diff --git a/docs/specs/image-metadata.md b/docs/specs/image-metadata.md
@@ -1,5 +1,11 @@
 # Image Metadata
 
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/18
+* CLI PR: https://github.com/devcontainers/cli/pull/188
+
+Below is the original proposal.
+
 ## Goal
 
 Record dev container config and feature metadata in prebuilt images, such that, the image and the built-in features can be used with a devcontainer.json (image-, Dockerfile- or Docker Compose-based) that does not repeat the dev container config or feature metadata. Other tools should be able to record the same metadata without necessarily using features themselves.
diff --git a/docs/specs/parallel-lifecycle-script-execution.md b/docs/specs/parallel-lifecycle-script-execution.md
@@ -1,10 +1,18 @@
-# Parallel lifecycle script execution
+# Parallel Lifecycle Script Execution
+
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/83
+* CLI PR: https://github.com/devcontainers/cli/pull/172
+
+Below is the original proposal.
+
+## Goal
 
 Support executing multiple lifecycle scripts in parallel by providing them in `object` form.
 
 ## Motivation
 
-Devcontainers supports a single command for each of its lifecycle scripts. While serial execution of multiple commands can be achieved with `;`, `&&`, etc. parallel is less straightforward and so deserves first-class support.
+Dev containers support a single command for each of their lifecycle scripts. While serial execution of multiple commands can be achieved with `;`, `&&`, etc. parallel is less straightforward and so deserves first-class support.
 
 ## Spec changes
 
diff --git a/docs/specs/secrets-support.md b/docs/specs/secrets-support.md
@@ -1,4 +1,10 @@
-# First class secrets support in dev containers implementations
+# First Class Secrets Support
+
+This has now been implemented:
+* Discussion issue: https://github.com/devcontainers/spec/issues/219
+* CLI PR: https://github.com/devcontainers/cli/pull/493
+
+Below is the original proposal.
 
 ## What are secrets
 Secrets are variables that hold sensitive values and need to be handled securely at all times (API keys, passwords etc.). Users can change a secret's value at any time, and a conforming dev containers implementation should support dynamically changing secrets without having to rebuild the container.
diff --git a/docs/specs/supporting-tools.md b/docs/specs/supporting-tools.md
@@ -1,4 +1,4 @@
-# Supporting tools and services
+# Supporting Tools and Services
 
 **Note: For the latest set of supporting tools, please check out https://containers.dev/supporting.**
 
diff --git a/proposals/README.md b/proposals/README.md
@@ -0,0 +1,7 @@
+# Proposals
+
+The files in this folder detail active proposals to the Dev Container Specification.
+
+We add any proposal to the [**proposals folder**](https://github.com/devcontainers/spec/tree/main/proposals), only if the proposal is accepted. It stays in that folder until the implementation is in progress. Once code/schema changes are released, we move it into the [**specs folder**](https://github.com/devcontainers/spec/tree/main/docs/specs).
+
+> **Note:** Our [contributing.md](/contributing.md) documents guidelines on contributing to the spec, as well as labels (proposal and finalization) defined for this process for GitHub issues.

Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Dev container specification`
	`1`	`+# Dev Container Specification`
`2`	`2`
`3`	`3`	`The purpose of the Development Container Specification is to provide a way to enrich containers with the content and metadata necessary to enable development inside them. These container environments should be easy to use, create, and recreate.`
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Dev Container metadata reference`
	`1`	`+# Dev Container Metadata Reference`
`2`	`2`
`3`	`3`	The `devcontainer.json` file contains any needed metadata and settings required to configurate a development container for a given well-defined tool and runtime stack. It can be used by [tools and services that support the dev container spec](supporting-tools.md) to create a development environment that contains one or more development containers.
`4`	`4`
Original file line number	Diff line number	Diff line change
`@@ -1,4 +1,4 @@`
`1`		`-# Supporting tools and services`
	`1`	`+# Supporting Tools and Services`
`2`	`2`
`3`	`3`	`Note: For the latest set of supporting tools, please check out https://containers.dev/supporting.`
`4`	`4`