Proposal: Add localFeaturesRoot for flexible local feature paths

[tennisleng]

Summary

This proposal addresses Issue #671 - making it easier to reuse local Features in dev containers.

Problem

Users who want to manage a collection of their own dev container configurations and Features in a single repository face significant friction. The current specification requires local Features to be stored within the .devcontainer/ folder at the project workspace folder root, which makes reusing Features across different dev container configurations difficult.

Solution

This PR introduces a new localFeaturesRoot property for devcontainer.json that allows users to specify a custom base directory for resolving local Feature paths.

Property Definition

Property	Type	Description
localFeaturesRoot	string	Path (relative to the folder containing devcontainer.json) that serves as the base for resolving local Feature paths. Defaults to . (current behavior).

Example Usage

{
    "name": "My Project",
    "image": "mcr.microsoft.com/devcontainers/base:ubuntu",
    "localFeaturesRoot": "../../shared-features",
    "features": {
        "./my-feature": {}  // Resolves to shared-features/my-feature
    }
}

Changes Made

1. proposals/flexible-local-feature-paths.md - New proposal document with full specification
2. docs/specs/devcontainerjson-reference.md - Added localFeaturesRoot property to the reference
3. docs/specs/devcontainer-features-distribution.md - Updated "Locally referenced Features" section with new property documentation and examples
4. schemas/devContainer.base.schema.json - Added localFeaturesRoot property to the JSON schema

Backward Compatibility

This change is fully backward compatible:

• The localFeaturesRoot property is optional
• When not specified, behavior is identical to current spec
• Existing configurations continue to work without modification

Implementation Notes

This is a specification-only proposal. The actual implementation would need to be done in the devcontainers/cli repository.

---

Fixes #671

[tennisleng]

@microsoft-github-policy-service agree