Move settings and extensions properties to vscode namespace

[chrmarti]

These VS Code-specific properties are currently top-level. The proposal is to introduce a vscode property for VS Code-specific configuration and move these two properties there.

We can copy the properties in the schema, keeping the old properties as 'deprecated' for compatibility.

One open question is how we can include runtime-specific parts of the JSON schema. For those runtimes we know of, we can reference or inline the schema. For now I suggest to keep these properties in the same schema file.

Interestingly settings and extensions also apply to Codespaces which already has a codespaces property for its own configuration.

/cc @bamurtaugh @Chuxel @jkeech

[bamurtaugh]

Are runtime-specific parts those under the "build" property?

[Chuxel]

@bamurtaugh @chrmarti Right now there's really three properties for VS Code that fall into this category I think. (Codespaces is discussing several):

• extensions
• settings
• devPort (since this is for VS Code server specifically)

Every other property would apply to other tools near as I can tell.

Couple thoughts/questions to future proof a bit here.

1. Should we have a top level property for that is for all tool/service/product specific properties? This would avoid name collisions down the road for other top level properties.

2. How would another tool or service "claim" a property? What are the requirements to avoid sitting on a name that the organization does not own? e.g. the person who claims it must have an email address from the organization that owns the tool or service.

3. When would we accept / not accept additions to a tool/service specific property additions to the schema?

For example, for question 1, we could do something like:

"product": {
    "vscode": {
        "extensions": [],
        "settings": {},
        "devPort": 3000
     },
    "codespaces": {
    }
}

To avoid having to type product when only one is in use, we could allow "product.vscode" as well much like settings.json:

"product.vscode": {
    "extensions": [],
    "settings": {},
    "devPort": 3000
}

For question 2, often what formats do is require the use of a domain that the company owns. That does get a bit verbose though. Otherwise do we need a process for people to claim a property, and then for question 3 only they get to state what should be added?

[chrmarti]

Are runtime-specific parts those under the "build" property?

"build" has container runtime (Docker) specific properties (there are several others, e.g., "dockerComposeFile"). I meant "dev container runtime" (currently only Remote-Containers and Codespaces).

1. Should we have a top level property for that is for all tool/service/product specific properties? This would avoid name collisions down the road for other top level properties.
2. How would another tool or service "claim" a property? What are the requirements to avoid sitting on a name that the organization does not own? e.g. the person who claims it must have an email address from the organization that owns the tool or service.

I like the brevity of top-level "vscode" and "codespaces" properties, but we should also allow for tools and new dev container runtimes to have their own subproperties in (e.g. a very generic) "customizations" without the need for coordinating with us. For a dev container runtime to get its own top-level property, we would expect contacts, documentation, issue tracker and an active user base. I expect there will be very few dev container runtimes compared to the number of tools that would go under "customizations". For tools we will recommend the use of domain names (or GitHub repository names) under "customizations".

{
	// ...
	"vscode": {
		"extensions": [],
		"settings": {},
		"devPort": 3000
	},
	"codespaces": {
	},
	"customizations": {
		"example.com": {
			"foo": "bar"
		},
		"foobar.com": {
			// ...
		}
	}
}

3. When would we accept / not accept additions to a tool/service specific property additions to the schema?

We need a way to reference the other dev container runtime's schema. Having the VS Code properties in the main schema is only an interim solution. Changes to their schema will then be under their control.

[Chuxel]

We need a way to reference the other dev container runtime's schema. Having the VS Code properties in the main schema is only an interim solution. Changes to their schema will then be under their control.

Yeah makes sense. That's partly why I was thinking about putting these things under a common property - different tools and their related schemas could inadvertently collide at the top level. Something like customizations works for me.

[bamurtaugh]

customizations makes sense to me for other dev container runtimes. And I suppose a runtime owner could open an issue in this repo to discuss getting their property added as a top-level to the schema, if they have the necessary support and user base?

[Chuxel]

customizations makes sense to me for other dev container runtimes. And I suppose a runtime owner could open an issue in this repo to discuss getting their property added as a top-level to the schema, if they have the necessary support and user base?

@bamurtaugh Yeah I and I think we'll want to publicly document the owner of the namespace. Helps be explicit that it's not something we manage explicitly.

[chrmarti]

[Update: Added customizations to the checklist base on feedback below. Added devPort as noted before.]
[Update 2: Move milestones to allow for more time for discussion.]

Doing this in 2 stages will allow the support for the new properties to roll out before they become used more widely:

• April
  • Add "vscode" property with "extensions", "settings" and "devPort" subproperties to implementation and schema.
  • Show a warning when the old and the new property (both "extensions" or both "settings" or both "devPort") are used in the same devcontainer.json.
  • Add "customizations" property as a JSON object with additional properties allowed.
• May
  • Update definitions in vscode-dev-containers to use the new properties.
  • Prefer the new properties when editing by UI command (only 2 cases).
  • Document customizations in contributing.md

At a future point we might want offer a code action to move the old properties over to the new properties (e.g., when there are more of them). No need to break existing configurations though.

For the devcontainer-features.json we can deprecate the old properties in the schema (but still read them) and start using the new ones.

[Chuxel]

@chrmarti Given, gitpod-io/gitpod#7721, I think we've already got a use case here for customizations. In addition, given our intent to have this be an open spec, I think including a customizations property will be important. Not every tool will want to ask for a top level property particularly when they're evaluating support. (Though in this case we could clearly add one if desirable.) We'd want a place for non-VS Code based tools and services to experiment or add provisional support for the format. I think all of us have looked at a format and decided not to use it based on a perception that it is proprietary given how the format is structured.

Either way, we'll want to advertise how people can "reserve" a top level property in the schema (if we keep it at that level) rather than leaving it implicit. I worry about name conflicts if it's a "free for all" at the top level. Perhaps we should describe this in contributing.md?

EDIT: I also think we can separate when it is a general part of the spec that is a way for external processors to augment the format from when the reference implementation supports it. Many of the things I'm talking about would be tool/service specific that may or may not be in the reference implementation - though obviously the more the merrier there.

[bamurtaugh]

I worry about name conflicts if it's a "free for all" at the top level. Perhaps we should describe this in contributing.md?

Documenting customizations in contributing.md makes sense to me. I assume we'd want to wait to describe it until it's actually implemented (not just an fyi right now, so that users don't try to use it already). Unless we wanted to give a more forward look and mention it right now (perhaps linking to this issue; folks who get to this repo may be interested in How can I contribute my own subproperties?), then update contributing.md once it's actually implemented?

[Chuxel]

Yeah, I was thinking once we've finalized this proposal.

[chrmarti]

Adding customizations to the check list above. 👍

I think of customizations as something mainly other tools (building on top of the reference or some other implementation) would use (maybe we could use it for temporary explorations). It will be a JSON object with no properties in the schema, but additional properties allowed. We can request tools pick a sufficiently distinctive property name or, more restrictive, a domain name they own (e.g., "gitpod" vs. "gitpod.io") to group their custom properties in a JSON object under customizations.

[chrmarti]

Getting this ready for the February release as proposed above. Let me know if this needs further consideration before we can publish it in a stable release.

[bamurtaugh]

I added Document customizations in contributing.md to the checklist for March above - let me know if folks have other thoughts (on timing, where to document, wording).

[chrmarti]

Changes for February are available with Remote-Containers 0.223.0 (pre-release).

[jkeech]

One thing that is important in my mind is to not have a set of first-party/official products that are treated differently in the schema with a separate section for "unofficial" tools. As an open specification, each tool/product that uses devcontainer.json should have an equal playing field with respect to where and how they can extend the devcontainer.json schema for their product-specific customizations.

In order to support this, I would propose that we do not have top-level codespaces and vscode blocks in the schema with everything else under customizations. We could instead have codespaces and vscode under customizations.

{
    "customizations": {
        "vscode": {          
        },
        "codespaces": {
        },
        "gitpod": {
        },
        "someOtherProduct": {
        },
    }
}

[chrmarti]

My main argument for products running dev containers getting their own top-level property is simplicity of the format. Any such product could ask to be included there, maybe we would require a JSON schema we can reference. Other kinds of tools would remain under customizations which can be self-serviced without us doing anything.

[jkeech]

I feel like it's not a great experience to have an official/unofficial split. A few reasons:

1. It gives the appearance that some tools are treated specially and other tools are not welcome or as free to adopt this specification and extend it for their needs
2. Every tool is going to want to be in the special set of official ones, and I don't think we should be the arbiters of which ones are allowed or are "good enough" to be in the official set
3. If you start an unofficial one and later switch to be official, it requires all of your users to alter their devcontainer.json files to use a different property name/location. And then the tool needs to build back-compat code to read from both locations, etc.

The same thing is true for the presentation of published definitions -- I don't want us to have an official set and an unofficial set. Instead, we should just say who the publisher is and let the user decide whether they trust that publisher or not. That follows the verified publisher pattern of many other registries and doesn't result in having a two-tiered system where some things are more favored than others.

[bamurtaugh]

As this is in finalization, should we work on the action items here (i.e. updating definitions and docs)?

[chrmarti]

We moved the timeline by another month (updated the above comment). So we now publish and deploy the support for the new properties in April and can start using them by default in May.

[bamurtaugh]

We've addressed the first item in the May checklist (updating samples and docs).

Have we addressed the second item: Prefer the new properties when editing by UI command (only 2 cases)?

Item 3 mentions documenting in contributing.md, and I opened the following PR: #34. Ed is also documenting customizations in the initial version of the spec.

[chrmarti]

Doing Prefer the new properties when editing by UI command (only 2 cases) now.

Looks like we are done. Closing this issue. Thanks everyone!