From 79e501ad6529aff28dc7d02e92d9f0fc182b4284 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 21 Jun 2022 17:27:25 +0000 Subject: [PATCH 1/6] Changes after discussion --- proposals/devcontainer-features.md | 23 ++++++++++++++++------- 1 file changed, 16 insertions(+), 7 deletions(-) diff --git a/proposals/devcontainer-features.md b/proposals/devcontainer-features.md index 4320c120..0e80a769 100644 --- a/proposals/devcontainer-features.md +++ b/proposals/devcontainer-features.md @@ -6,7 +6,19 @@ From a practical point of view, features are folders that contain units of code Features can be defined by a `devcontainer-feature.json` file in the root folder of the feature. The file is optional for backwards compatibility but it is required for any new features being authored. -Features are to be executed in sequence as defined in `devcontainer.json`. +By default features are executed by an order selected by the tool that implements the spec based in the following: + +- `runsAfter` property defined as part of `devcontainer-feature.json`. +- id. + +The tool uses the `runsAfter` propery to intelligently manage this order and ensure that if there are relationships betwen the features they are respected. + +In case an end user needs to control the order of execution we are adding the `overrideFeatureInstallOrder` to `devcontainer.json` + +| Property | Type | Description | +| :--- | :--- | :--- | +| overrideFeatureInstallOrder | array | Array made of the Id's of the features in the order the user wants them to be installed. | + ## Folder Structure @@ -90,12 +102,11 @@ In most cases, the `devcontainer-collection.json` file can be generated automati ## devcontainer.json properties -Features are referenced in `devcontainer.json` , where the `features` tag consists of an array with the ordered list of features to be included in the container image. +Features are referenced in `devcontainer.json` , where the `features` tag consists of an object tag starting with the id of the feature. and including the values of the options to pass to the feature itself. The properties are: | Property | Type | Description | | :--- | :--- | :--- | -| id | string | Reference to the particular feature to be included. | | options | object | Type of the option .| The `id` is the main reference point for how to find and download a particular feature. `id` can be defined in any of the following ways: @@ -135,11 +146,9 @@ A release consists of the following: There are several things to keep in mind for an application that implements features: -- Features are executed in the order defined in devcontainer.json -- It should be possible to execute a feature multiple times with different parameters. +- The order of execution of features is determined by the application based on the `installAfter` property by feature authors and can be overriden by users if necesarry with the `overrideFeatureInstallOrder` in `devcontainer.json`. - Features are used to create an image that can be used to create a container or not. - Parameters like `privileged`, `init` are included if just 1 feature requires them. - Parameters like `capAdd`, `securityOp` are concatenated. - ContainerEnv is added before the feature is executed as `ENV` commands in the docker file. -- Features are added to an image in two passes. One for `aquire` scripts and another for `install` scripts. -- Each script executes as its own layer to aid in caching and rebuilding. \ No newline at end of file +- Each feature script executes as its own layer to aid in caching and rebuilding. \ No newline at end of file From 6c4e2afa2cc79a141d50734463f8e51173776f85 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Tue, 21 Jun 2022 14:03:52 -0700 Subject: [PATCH 2/6] Apply suggestions from code review Co-authored-by: Josh Spicer Co-authored-by: Samruddhi Khandale --- proposals/devcontainer-features.md | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/proposals/devcontainer-features.md b/proposals/devcontainer-features.md index 0e80a769..c754dd44 100644 --- a/proposals/devcontainer-features.md +++ b/proposals/devcontainer-features.md @@ -6,14 +6,20 @@ From a practical point of view, features are folders that contain units of code Features can be defined by a `devcontainer-feature.json` file in the root folder of the feature. The file is optional for backwards compatibility but it is required for any new features being authored. -By default features are executed by an order selected by the tool that implements the spec based in the following: +By default, features are installed in an order selected by the implementing tool. + +If any of the following properties in the feature's `devcontainer-feature.json, or the user's `devcontainer.json` are provided, the ordered indicated by the propert(ies) are respected. - `runsAfter` property defined as part of `devcontainer-feature.json`. - id. The tool uses the `runsAfter` propery to intelligently manage this order and ensure that if there are relationships betwen the features they are respected. -In case an end user needs to control the order of execution we are adding the `overrideFeatureInstallOrder` to `devcontainer.json` +An end-user can explicitly provide an installation order for features given the `overrideFeatureInstallOrder` property of `devcontainer.json`. + +All feature `id` provided in `overrideFeatureInstallOrder` must also exist in the `features` property of a user's `devcontainer.json`. + +The provided features, indicated by `id`, will be installed in the specified order. Any remaining features in the features object that are not mentioned in the array will be installed in an undefined/implicit order, as determined as optimal by the tooling. | Property | Type | Description | | :--- | :--- | :--- | @@ -102,12 +108,12 @@ In most cases, the `devcontainer-collection.json` file can be generated automati ## devcontainer.json properties -Features are referenced in `devcontainer.json` , where the `features` tag consists of an object tag starting with the id of the feature. and including the values of the options to pass to the feature itself. +Features are referenced in `devcontainer.json` , where the `features` tag consists of an object tag starting with the id of the feature and including the values of the options to pass to the feature itself. The properties are: | Property | Type | Description | | :--- | :--- | :--- | -| options | object | Type of the option .| +| options | object | Type of the option. | The `id` is the main reference point for how to find and download a particular feature. `id` can be defined in any of the following ways: From e70288227afdcdc6e8b4c657cdc226be57b5a07a Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Mon, 27 Jun 2022 10:28:18 -0700 Subject: [PATCH 3/6] Apply suggestions from code review Co-authored-by: Brigit Murtaugh --- proposals/devcontainer-features.md | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/proposals/devcontainer-features.md b/proposals/devcontainer-features.md index c754dd44..d53986c4 100644 --- a/proposals/devcontainer-features.md +++ b/proposals/devcontainer-features.md @@ -8,12 +8,12 @@ Features can be defined by a `devcontainer-feature.json` file in the root folder By default, features are installed in an order selected by the implementing tool. -If any of the following properties in the feature's `devcontainer-feature.json, or the user's `devcontainer.json` are provided, the ordered indicated by the propert(ies) are respected. +If any of the following properties are provided in the feature's `devcontainer-feature.json`, or the user's `devcontainer.json`, the order indicated by the propert(ies) are respected. - `runsAfter` property defined as part of `devcontainer-feature.json`. -- id. +- `id`. -The tool uses the `runsAfter` propery to intelligently manage this order and ensure that if there are relationships betwen the features they are respected. +The tool uses the `runsAfter` property to intelligently manage this order and ensure that if there are relationships between the features, they are respected. An end-user can explicitly provide an installation order for features given the `overrideFeatureInstallOrder` property of `devcontainer.json`. @@ -152,9 +152,9 @@ A release consists of the following: There are several things to keep in mind for an application that implements features: -- The order of execution of features is determined by the application based on the `installAfter` property by feature authors and can be overriden by users if necesarry with the `overrideFeatureInstallOrder` in `devcontainer.json`. +- The order of execution of features is determined by the application, based on the `installAfter` property used by feature authors. It can be overridden by users if necessary with the `overrideFeatureInstallOrder` in `devcontainer.json`. - Features are used to create an image that can be used to create a container or not. -- Parameters like `privileged`, `init` are included if just 1 feature requires them. -- Parameters like `capAdd`, `securityOp` are concatenated. -- ContainerEnv is added before the feature is executed as `ENV` commands in the docker file. +- Parameters like `privileged` and `init` are included if just 1 feature requires them. +- Parameters like `capAdd` and `securityOp` are concatenated. +- `containerEnv` is added before the feature is executed as `ENV` commands in the Dockerfile. - Each feature script executes as its own layer to aid in caching and rebuilding. \ No newline at end of file From 8d05cb8b252170de6d7a4730b6e41de80bf051de Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Wed, 29 Jun 2022 16:52:43 +0000 Subject: [PATCH 4/6] Changes from PR --- proposals/devcontainer-features.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/proposals/devcontainer-features.md b/proposals/devcontainer-features.md index 4c644438..0e7da820 100644 --- a/proposals/devcontainer-features.md +++ b/proposals/devcontainer-features.md @@ -10,7 +10,7 @@ By default, features are installed in an order selected by the implementing tool If any of the following properties are provided in the feature's `devcontainer-feature.json`, or the user's `devcontainer.json`, the order indicated by the propert(ies) are respected. -- `runsAfter` property defined as part of `devcontainer-feature.json`. +- `installsAfter` property defined as part of `devcontainer-feature.json`. - `id`. The tool uses the `runsAfter` property to intelligently manage this order and ensure that if there are relationships between the features, they are respected. @@ -79,6 +79,8 @@ The properties of the file are as follows: | capAdd | array | Additional capabilities needed by the feature. | | securityOpt | array | Security options needed by the feature. | | entrypoint | string | Set if the feature requires an entrypoint. | +| customizations | object | Product specific properties, each namespace under `customizations` is treated as a separate set of properties. For each of this sets the object is parsed, values are replaced while arrays are set as a union. | +| installsAfter | array | Array of Id's of features that should execute before this one. Allows control for feature authors on soft dependencies between different features. | Options @@ -110,10 +112,6 @@ In most cases, the `devcontainer-collection.json` file can be generated automati Features are referenced in `devcontainer.json` , where the `features` tag consists of an object tag starting with the id of the feature and including the values of the options to pass to the feature itself. -The properties are: -| Property | Type | Description | -| :--- | :--- | :--- | -| options | object | Type of the option. | The `id` is the main reference point for how to find and download a particular feature. `id` can be defined in any of the following ways: From a58efe01a1cbd6af9442790a49454b8e5dfeb2a4 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Wed, 29 Jun 2022 16:56:24 +0000 Subject: [PATCH 5/6] Changes. --- proposals/devcontainer-features.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/proposals/devcontainer-features.md b/proposals/devcontainer-features.md index 0e7da820..759f8f63 100644 --- a/proposals/devcontainer-features.md +++ b/proposals/devcontainer-features.md @@ -70,8 +70,6 @@ The properties of the file are as follows: | licenseURL | string | Url that points to the license of the feature. | | version | string | Version of the feature. | | keywords | array | List of keywords relevant to a user that would search for this definition/feature. | -| install.app | string | App to execute.| -| install.file | string | Parameters/script to execute (defaults to install.sh).| | options | object | Possible options to be passed as environment variables to the execution of the scripts | | containerEnv | object | A set of name value pairs that sets or overrides environment variables. | | privileged | boolean | If privileged mode is required by the feature. | From 36b63c9c0e6e0101d1ac34b615a100d5acc5209a Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Wed, 29 Jun 2022 16:58:34 +0000 Subject: [PATCH 6/6] Added overrideFeatureInstallOrder --- proposals/devcontainer-features.md | 1 + 1 file changed, 1 insertion(+) diff --git a/proposals/devcontainer-features.md b/proposals/devcontainer-features.md index 759f8f63..93b5c80d 100644 --- a/proposals/devcontainer-features.md +++ b/proposals/devcontainer-features.md @@ -12,6 +12,7 @@ If any of the following properties are provided in the feature's `devcontainer-f - `installsAfter` property defined as part of `devcontainer-feature.json`. - `id`. +- `overrideFeatureInstallOrder` in `devcontainer.json`. Allows users to control the order of execution of their features. The tool uses the `runsAfter` property to intelligently manage this order and ensure that if there are relationships between the features, they are respected.