From fa0fe538c2c9a7162ec6bc904eb51b5d9948c436 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Wed, 1 Jun 2022 22:34:30 +0000 Subject: [PATCH 1/4] First pass --- proposals/devcontainer-distribution.md | 71 ++++++++++++++++++++++++++ 1 file changed, 71 insertions(+) create mode 100644 proposals/devcontainer-distribution.md diff --git a/proposals/devcontainer-distribution.md b/proposals/devcontainer-distribution.md new file mode 100644 index 00000000..46436524 --- /dev/null +++ b/proposals/devcontainer-distribution.md @@ -0,0 +1,71 @@ +# Community creation of templates and features and their distribution. + +This proposal is created to arrive at a schema where different communities and organizations can create features and devcontainer templates and make them discoverable to users. + +The proposal centers on the following ideas: + +- Discoverability for users both on the web (github.com) and on any tools that implement the [Dev container specification](../docs/specs/devcontainer-reference.md). +- Users can validate the origin of the template or feature that they want to use. +- Users can pin a particular version of a feature to allow consistent repeatable environments. + +# Proposal + +## Github Topics + +This can be achieved with the use of [GitHub Topics](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics), specifically the [devcontainers](https://github.com/topics/devcontainers) topic. Additionally the repositories can be marked with **devcontainers-templates** and/or **devcontainers-features** to mark specifically the contents of the repository. + +Any UI application can leverage this search to provide a list of repositories that contain features or templates and present them for their users. The application would query the latest release and obtain the details to show them to the users. + +An implementation of the spec can also use other mechanisms to speed up or improve the user experience while searching. + +At the same time it should contain a way for users to directly reference a repository containing the features/templates that they want to use. + +## Releases + +As a distribution and storage mechanism we propose using GitHub releases. The releases would contain compressed files with the source code of the feature or template. Together with the release the corresponding metadata file would be included either **devcontainer-feature.json**, **devcontainer-template.json** or **devcontainer-collection.json**. + +## Collections + +Features and/or templates can be distributed both as a single unit or as a **collection** of them. In case they are released as a collection the release should include a **devcontainer-collection.json** file that groups the information of each feature/template contained. + +| Property | Type | Description | +| :--- | :--- | :--- | +| publisher | string | The organization/user that publishes this group of templates/features. Must match with the repository user in github.| +| repository | string | The repository where this collection is contained.| +| version | string | Version information of this collection list.| +| features | array | The list of features that are contained in this collection. Same information as the metadata file for the feature.| +| templates | array | The list of templates contained in this collection. Same information as the metadata file for the definition.| + +Its important to note the following about collections: + +- It is recomended that they are created automatically as part of the release process. +- Ids would get the collection repository added to them. (e.g. for 'https://github.com/community/features' then 'community/features' to 'myfeature1' for a feature with that id) +- The links to the release files would be added. +- Date. +- Version. + +## Templates specifics + +By their nature templates are single use since they are just a group of files that are copied over to an end users repository and used to kickstart a **dev container** configuration. + +Due to this the implementing application needs to ensure that the user is able to inspect all files included in the template and that no code is executed automatically until a specific action by a user demands it. + +## Features specifics + +Since features contain code that can be executed multiple times by different users the security of the contents is important, for this we propose: + +- Any application that implements the [Dev container spec](../docs/specs/devcontainer-reference.md) must provide a way for the user to add a feature to their `devcontainer.json` file in a way that the code can be inspected before it executes the first time. +- This action should create a **devcontainer.lock** file next to the main `devcontainer.json` file that contains the checksums of the particular release referenced. +- Users can commit this file to their repository so that the application can berify the checksum each time it rebuilds the container, throwing an error if they not match. +- If users want to update to a newer version they can either delete the **devcontainer.lock** file, delete the particular entry or reference a different version of it on their `devcontainer.json` file. If the version stored in both files doesn't match, the application should update the entry on the next build. +- If during a first build the **devcontainer.lock** file does not exist, it should be created as part of the build process if and when it succeeds. + +The **devcontainer.lock** contains an array of: + +| Property | Type | Description | +| :--- | :--- | :--- | +| id | string | The fully qualified id of the feature as defined [here](./devcontainer-features.md#devcontainerjson-properties).| +| options | string | The same options object passed to the feature in `devcontainer.json`| +| checksum | string | The checksum of the downloaded compressed release file.| + +It is important to note that, like in `devcontainer.json` features can appear more than one time and are assumed to be in the same order. \ No newline at end of file From e78ed2fec476b387dcb9b5b312e90d8c85d7fcd3 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Fri, 3 Jun 2022 15:54:53 -0700 Subject: [PATCH 2/4] Apply suggestions from code review Co-authored-by: Brigit Murtaugh --- proposals/devcontainer-distribution.md | 32 +++++++++++++------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/proposals/devcontainer-distribution.md b/proposals/devcontainer-distribution.md index 46436524..13b5e673 100644 --- a/proposals/devcontainer-distribution.md +++ b/proposals/devcontainer-distribution.md @@ -1,42 +1,42 @@ -# Community creation of templates and features and their distribution. +# Community contributions of templates and features -This proposal is created to arrive at a schema where different communities and organizations can create features and devcontainer templates and make them discoverable to users. +This proposal is created to arrive at a schema where different communities and organizations can create features and dev container templates and make them discoverable to users. The proposal centers on the following ideas: - Discoverability for users both on the web (github.com) and on any tools that implement the [Dev container specification](../docs/specs/devcontainer-reference.md). - Users can validate the origin of the template or feature that they want to use. -- Users can pin a particular version of a feature to allow consistent repeatable environments. +- Users can pin a particular version of a feature to allow consistent, repeatable environments. # Proposal ## Github Topics -This can be achieved with the use of [GitHub Topics](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics), specifically the [devcontainers](https://github.com/topics/devcontainers) topic. Additionally the repositories can be marked with **devcontainers-templates** and/or **devcontainers-features** to mark specifically the contents of the repository. +A set of discoverable dev container-related repos can be achieved with the use of [GitHub Topics](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). You may explore repos that GitHub has automatically considered part of the [devcontainers](https://github.com/topics/devcontainers) topic. If you'd like your template or feature repo to be easily discoverable to the community, you may add the **devcontainers-templates** and/or **devcontainers-features** topic. You may read more on how to do this in the [topics guide](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/classifying-your-repository-with-topics). -Any UI application can leverage this search to provide a list of repositories that contain features or templates and present them for their users. The application would query the latest release and obtain the details to show them to the users. +Any UI application can leverage this search to provide a list of repositories that contain features or templates and present them to their users. The application would query the latest release of repos within the list and obtain their details to show them to the users. An implementation of the spec can also use other mechanisms to speed up or improve the user experience while searching. -At the same time it should contain a way for users to directly reference a repository containing the features/templates that they want to use. +At the same time, it should include a way for users to directly reference a repository containing the features or templates they want to use. ## Releases -As a distribution and storage mechanism we propose using GitHub releases. The releases would contain compressed files with the source code of the feature or template. Together with the release the corresponding metadata file would be included either **devcontainer-feature.json**, **devcontainer-template.json** or **devcontainer-collection.json**. +As a distribution and storage mechanism, we propose using GitHub releases. The releases would contain compressed files with the source code of the feature or template. Included with the release the corresponding metadata file would be either **devcontainer-feature.json**, **devcontainer-template.json** or **devcontainer-collection.json**. ## Collections -Features and/or templates can be distributed both as a single unit or as a **collection** of them. In case they are released as a collection the release should include a **devcontainer-collection.json** file that groups the information of each feature/template contained. +Features and/or templates can be distributed both as a single unit or as a **collection** of them. In case they are released as a collection, the release should include a **devcontainer-collection.json** file that groups the information of each feature or template contained. | Property | Type | Description | | :--- | :--- | :--- | -| publisher | string | The organization/user that publishes this group of templates/features. Must match with the repository user in github.| +| publisher | string | The organization/user that publishes this group of templates/features. Must match with the repository user in GitHub.| | repository | string | The repository where this collection is contained.| | version | string | Version information of this collection list.| | features | array | The list of features that are contained in this collection. Same information as the metadata file for the feature.| | templates | array | The list of templates contained in this collection. Same information as the metadata file for the definition.| -Its important to note the following about collections: +It's important to note the following about collections: - It is recomended that they are created automatically as part of the release process. - Ids would get the collection repository added to them. (e.g. for 'https://github.com/community/features' then 'community/features' to 'myfeature1' for a feature with that id) @@ -46,18 +46,18 @@ Its important to note the following about collections: ## Templates specifics -By their nature templates are single use since they are just a group of files that are copied over to an end users repository and used to kickstart a **dev container** configuration. +By their nature, templates are single use since they are just a group of files that are copied over to an end user's repository and used to kickstart a **dev container** configuration. -Due to this the implementing application needs to ensure that the user is able to inspect all files included in the template and that no code is executed automatically until a specific action by a user demands it. +Because of this, the implementing application needs to ensure that the user is able to inspect all files included in the template and that no code is executed automatically until a specific action by a user demands it. ## Features specifics -Since features contain code that can be executed multiple times by different users the security of the contents is important, for this we propose: +Since features contain code that can be executed multiple times by different users, the security of the contents is important, and for this we propose: - Any application that implements the [Dev container spec](../docs/specs/devcontainer-reference.md) must provide a way for the user to add a feature to their `devcontainer.json` file in a way that the code can be inspected before it executes the first time. - This action should create a **devcontainer.lock** file next to the main `devcontainer.json` file that contains the checksums of the particular release referenced. -- Users can commit this file to their repository so that the application can berify the checksum each time it rebuilds the container, throwing an error if they not match. -- If users want to update to a newer version they can either delete the **devcontainer.lock** file, delete the particular entry or reference a different version of it on their `devcontainer.json` file. If the version stored in both files doesn't match, the application should update the entry on the next build. +- Users can commit this file to their repository so that the application can berify the checksum each time it rebuilds the container, throwing an error if they do not match. +- If users want to update to a newer version, they can either delete the **devcontainer.lock** file, delete the particular entry, or reference a different version of it in their `devcontainer.json` file. If the version stored in both files doesn't match, the application should update the entry on the next build. - If during a first build the **devcontainer.lock** file does not exist, it should be created as part of the build process if and when it succeeds. The **devcontainer.lock** contains an array of: @@ -65,7 +65,7 @@ The **devcontainer.lock** contains an array of: | Property | Type | Description | | :--- | :--- | :--- | | id | string | The fully qualified id of the feature as defined [here](./devcontainer-features.md#devcontainerjson-properties).| -| options | string | The same options object passed to the feature in `devcontainer.json`| +| options | string | The same options object passed to the feature in `devcontainer.json`.| | checksum | string | The checksum of the downloaded compressed release file.| It is important to note that, like in `devcontainer.json` features can appear more than one time and are assumed to be in the same order. \ No newline at end of file From 96d8d04c163385707d0c8bb714a76eef09ac7e25 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Fri, 3 Jun 2022 23:09:38 +0000 Subject: [PATCH 3/4] Changes from PR. --- proposals/devcontainer-distribution.md | 7 ++----- 1 file changed, 2 insertions(+), 5 deletions(-) diff --git a/proposals/devcontainer-distribution.md b/proposals/devcontainer-distribution.md index 13b5e673..5c5c48a2 100644 --- a/proposals/devcontainer-distribution.md +++ b/proposals/devcontainer-distribution.md @@ -39,10 +39,7 @@ Features and/or templates can be distributed both as a single unit or as a **col It's important to note the following about collections: - It is recomended that they are created automatically as part of the release process. -- Ids would get the collection repository added to them. (e.g. for 'https://github.com/community/features' then 'community/features' to 'myfeature1' for a feature with that id) -- The links to the release files would be added. -- Date. -- Version. +- When a **devcontainer-collection.json** file is created, the Id's of the features/templates should get the name of the collection added to them to aid in the search for the source. For example, in repository 'https://github.com/community/features' for a collection called 'collection', the resulting id would be 'community/features/collection/myFeature'. ## Templates specifics @@ -68,4 +65,4 @@ The **devcontainer.lock** contains an array of: | options | string | The same options object passed to the feature in `devcontainer.json`.| | checksum | string | The checksum of the downloaded compressed release file.| -It is important to note that, like in `devcontainer.json` features can appear more than one time and are assumed to be in the same order. \ No newline at end of file +The specification supports executing features multiple times with different options. This can be useful when a user wants to install multiple versions of sdk's, or simply execute whatever changes the feature makes to the operating system multiple times. \ No newline at end of file From 532f32d570c5017bdad43d67318de6324b9d1ff7 Mon Sep 17 00:00:00 2001 From: Edmundo Gonzalez <51725820+edgonmsft@users.noreply.github.com> Date: Fri, 3 Jun 2022 23:22:24 +0000 Subject: [PATCH 4/4] Clarifying comments. --- proposals/devcontainer-distribution.md | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/proposals/devcontainer-distribution.md b/proposals/devcontainer-distribution.md index 5c5c48a2..95ae41d6 100644 --- a/proposals/devcontainer-distribution.md +++ b/proposals/devcontainer-distribution.md @@ -38,8 +38,10 @@ Features and/or templates can be distributed both as a single unit or as a **col It's important to note the following about collections: -- It is recomended that they are created automatically as part of the release process. -- When a **devcontainer-collection.json** file is created, the Id's of the features/templates should get the name of the collection added to them to aid in the search for the source. For example, in repository 'https://github.com/community/features' for a collection called 'collection', the resulting id would be 'community/features/collection/myFeature'. +- It is recomended that the **devcontainer-collection.json** file is created automatically as part of the release process. +- The compressed release file should contain all the folders of the features/templates included in it. +- The names of the folders should coincide with the id of the feature/template itself. +- When a **devcontainer-collection.json** file is created, the Id's of the features/templatescontained in it should get the name of the collection added to them to aid in the search for the source. For example, in repository 'https://github.com/community/features' for a collection called 'collection', the resulting id would be 'community/features/collection/myFeature'. ## Templates specifics