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 Brigit Murtaugh (@bamurtaugh) Chuck Lantz (@Chuxel) John Keech (@jkeech)

[bamurtaugh]

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

[Chuxel]

Brigit Murtaugh (@bamurtaugh) Christof Marti (@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?

Brigit Murtaugh (@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]

Christof Marti (@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.