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.