Skip to content

Commit 5b8e14f

Browse files
aledbfclaude
andcommitted
fix(features)!: map and refuse legacy Feature ids as the reference does
Legacy and shorthand Feature ids now follow the reference CLI's getBackwardCompatibleFeatureId, getFeatureIdType and updateDeprecatedFeaturesIntoOptions in up, build, read-configuration, upgrade, features resolve-dependencies, features info and outdated: - Only exact legacy names (node, golang, …) map to ghcr.io/devcontainers/features/<name>:1, and log TS's "(!) WARNING: Using the deprecated '<id>' Feature" line. - A legacy name with a tag (node:18, node:1) and any other id without a '/' fail with "Legacy feature '<id>' not supported". - gradle, maven and jupyterlab move into the java/python Feature they are now an option of, before any Feature is resolved. - owner/repo/feat is an OCI reference whose registry is "owner", no longer ghcr.io/owner/repo/feat. - --skip-feature-auto-mapping is accepted and ignored, as in TS. - outdated reports what getRef parses as written: legacy ids are left out, and a Feature without published versions is reported empty. - The lockfile's integrity is looked up by the mapped id, so an entry under a legacy id doesn't pin it, as in TS. A ts-oracle golden pins the three TS functions, and five parity cases compare the user-visible results with the reference. BREAKING CHANGE: node:18-style ids, other names without a '/', and owner/repo/feat ids that relied on an implicit ghcr.io now fail or resolve as in the official CLI; docs/migration.md says how to write them. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
1 parent 6806c35 commit 5b8e14f

21 files changed

Lines changed: 948 additions & 244 deletions

‎docs/migration.md‎

Lines changed: 15 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -81,6 +81,21 @@ runs the official CLI is unaffected:
8181
`devcontainer features package . --output-folder output`.
8282
- A configuration that references a legacy GitHub Releases Feature fails, in
8383
`read-configuration` too, instead of silently leaving the Feature out.
84+
- Only the exact legacy Feature names (for example `node`, `golang`, `gradle`)
85+
map to `ghcr.io/devcontainers/features/<name>:1`, with a
86+
`(!) WARNING: Using the deprecated '<name>' Feature.` line. A legacy name with
87+
a tag, such as `node:18` or `node:1`, and any other name without a `/` fail
88+
with `Legacy feature '<id>' not supported.` Replace them with the published
89+
id, for example `ghcr.io/devcontainers/features/node:1` with the option
90+
`"version": "18"`.
91+
- An id such as `owner/repo/feature` is an OCI reference whose registry is
92+
`owner`; it no longer means `ghcr.io/owner/repo/feature`. Write the registry
93+
explicitly.
94+
- `--skip-feature-auto-mapping` no longer turns the legacy mapping off: the
95+
official CLI accepts the flag and ignores it.
96+
- `outdated` leaves legacy ids out, and reports a Feature whose versions cannot
97+
be listed with empty values (`{}` in JSON, `-` in text) instead of leaving it
98+
out.
8499
- `up` with `--id-label` and no workspace folder or configuration fails with
85100
`No dev container config and no workspace found.` instead of attaching to the
86101
matching container.

‎docs/parity/parity-matrix.yaml‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -348,6 +348,19 @@ initial_cases:
348348
current_status: match
349349
notes: "outdated writes JSON.stringify(outdated, undefined, process.stdout.isTTY ? ' ' : undefined): with stdout not a terminal, as here, the result is one unindented line ({\"features\":{}}, a local Feature having no versions). Go used to indent it always."
350350

351+
- id: outdated.legacy-ids-success
352+
lane: contract
353+
command: outdated
354+
priority: p1
355+
docker_required: false
356+
setup_cmd: "WORKSPACE=/tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}; rm -rf $WORKSPACE; mkdir -p $WORKSPACE/.devcontainer/local; printf '%s' '{\"id\":\"local\",\"version\":\"1.0.0\"}' > $WORKSPACE/.devcontainer/local/devcontainer-feature.json; printf '%s' '{\"image\":\"alpine:3\",\"features\":{\"node\":{},\"node:18\":{},\"terraform\":\"latest\",\"my-custom-feature\":{},\"owner/feat\":{},\"localhost:1/ns/feat:1\":{},\"./local\":{}}}' > $WORKSPACE/.devcontainer/devcontainer.json; echo WORKSPACE=$WORKSPACE"
357+
cleanup_cmd: "rm -rf /tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}"
358+
ts_cmd: "outdated --workspace-folder ${WORKSPACE} --output-format json"
359+
asserts: [exit_code, stdout_text]
360+
class: outdated
361+
current_status: match
362+
notes: "loadVersionInfo calls getRef on each id as written, without the legacy mapping: node, node:18, terraform, my-custom-feature and owner/feat do not parse and are left out, as is the local Feature. localhost:1/ns/feat:1 parses; its tags cannot be listed (connection refused), and it is still reported, with no versions: {\"features\":{\"localhost:1/ns/feat:1\":{}}}. Go used to map the legacy ids to ghcr.io and report them, and to leave out a Feature without versions."
363+
351364
- id: outdated.text-without-features-success
352365
lane: contract
353366
command: outdated
@@ -856,6 +869,60 @@ initial_cases:
856869
current_status: match
857870
notes: "A bare Feature id ('myfeature') is a legacy id TS rejects ('Legacy feature myfeature not supported...'), exit 1 with no result. Go used to drop the Feature error silently and print a configuration without the Feature."
858871

872+
- id: read-configuration.legacy-feature-id-with-tag-error
873+
lane: contract
874+
command: read-configuration
875+
priority: p1
876+
docker_required: false
877+
setup_cmd: "WORKSPACE=/tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}; rm -rf $WORKSPACE; mkdir -p $WORKSPACE/.devcontainer; printf '%s' '{\"image\":\"alpine:3\",\"features\":{\"node:18\":{}}}' > $WORKSPACE/.devcontainer/devcontainer.json; echo WORKSPACE=$WORKSPACE"
878+
cleanup_cmd: "rm -rf /tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}"
879+
ts_cmd: "read-configuration --workspace-folder ${WORKSPACE} --include-merged-configuration"
880+
asserts: [exit_code, stderr_normalized]
881+
class: features
882+
current_status: match
883+
notes: "getBackwardCompatibleFeatureId maps only the exact legacy names: 'node:18' stays as written and getFeatureIdType refuses it ('Legacy feature 'node:18' not supported...'), exit 1. Go used to map it to ghcr.io/devcontainers/features/node:18 and fail fetching it."
884+
885+
- id: read-configuration.deprecated-feature-into-options-error
886+
lane: contract
887+
command: read-configuration
888+
priority: p1
889+
docker_required: false
890+
setup_cmd: "WORKSPACE=/tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}; rm -rf $WORKSPACE; mkdir -p $WORKSPACE/.devcontainer; printf '%s' '{\"image\":\"alpine:3\",\"features\":{\"gradle\":{},\"node:18\":{}}}' > $WORKSPACE/.devcontainer/devcontainer.json; echo WORKSPACE=$WORKSPACE"
891+
cleanup_cmd: "rm -rf /tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}"
892+
ts_cmd: "read-configuration --workspace-folder ${WORKSPACE} --include-merged-configuration"
893+
asserts: [exit_code, stderr_normalized]
894+
class: features
895+
current_status: match
896+
notes: "updateDeprecatedFeaturesIntoOptions moves gradle into a ghcr.io/devcontainers/features/java:1 it appends after the other Features and logs '(!) WARNING: Using the deprecated 'gradle' Feature...' before any Feature is resolved, so node:18 is refused before java is requested: no network. Go used to resolve gradle in place, requesting java first."
897+
898+
- id: read-configuration.feature-shorthand-registry-error
899+
lane: contract
900+
command: read-configuration
901+
priority: p1
902+
docker_required: false
903+
network_required: true
904+
setup_cmd: "WORKSPACE=/tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}; rm -rf $WORKSPACE; mkdir -p $WORKSPACE/.devcontainer; printf '%s' '{\"image\":\"alpine:3\",\"features\":{\"devcontainers/features/node:1\":{}}}' > $WORKSPACE/.devcontainer/devcontainer.json; echo WORKSPACE=$WORKSPACE"
905+
cleanup_cmd: "rm -rf /tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}"
906+
ts_cmd: "read-configuration --workspace-folder ${WORKSPACE} --include-merged-configuration"
907+
asserts: [exit_code]
908+
class: features
909+
current_status: match
910+
notes: "An id with a slash and no dot in its first segment is an OCI reference whose registry is that segment (getRef): 'devcontainers/features/node:1' is requested from the host devcontainers, which does not resolve, and the GitHub Releases fallback refuses the id, exit 1. Go used to prefix ghcr.io/ and install ghcr.io/devcontainers/features/node:1. Only the exit code is compared: TS ends with its GitHub Releases fallback, which this CLI does not implement (DIVERGENCES.md). network_required for the DNS lookup."
911+
912+
- id: read-configuration.skip-feature-auto-mapping-success
913+
lane: contract
914+
command: read-configuration
915+
priority: p1
916+
docker_required: false
917+
network_required: true
918+
setup_cmd: "WORKSPACE=/tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}; rm -rf $WORKSPACE; mkdir -p $WORKSPACE/.devcontainer; printf '%s' '{\"image\":\"alpine:3\",\"features\":{\"node\":{}}}' > $WORKSPACE/.devcontainer/devcontainer.json; echo WORKSPACE=$WORKSPACE"
919+
cleanup_cmd: "rm -rf /tmp/parity-${PARITY_CASE_ID}-${PARITY_SIDE}"
920+
ts_cmd: "read-configuration --workspace-folder ${WORKSPACE} --include-features-configuration --skip-feature-auto-mapping"
921+
asserts: [exit_code]
922+
class: features
923+
current_status: match
924+
notes: "TS declares --skip-feature-auto-mapping but generateFeaturesConfig never passes it to processFeatureIdentifier, so 'node' is still mapped to ghcr.io/devcontainers/features/node:1 with its deprecation warning, exit 0. Go used to honor the flag and fail to parse 'node' as a reference."
925+
859926
- id: read-configuration.local-feature-outside-devcontainer-error
860927
lane: contract
861928
command: read-configuration

‎internal/cli/build.go‎

Lines changed: 5 additions & 14 deletions
Original file line numberDiff line numberDiff line change
@@ -8,7 +8,6 @@ import (
88
"os"
99
"path/filepath"
1010
"slices"
11-
"strings"
1211

1312
"github.com/devcontainers/cli/internal/config"
1413
"github.com/devcontainers/cli/internal/docker"
@@ -37,7 +36,6 @@ type buildOpts struct {
3736
labels []string
3837
output string
3938
additionalFeatures string
40-
skipFeatureAutoMapping bool
4139
skipPersistCustoms bool
4240
experimentalLockfile bool
4341
experimentalFrozenLockfile bool
@@ -85,7 +83,7 @@ func newBuildCmd() *cobra.Command {
8583
f.StringVar(&opts.dockerComposePath, "docker-compose-path", "", "Docker Compose CLI path.")
8684
f.StringVar(&opts.additionalFeatures, "additional-features", "", "Additional features JSON.")
8785
f.String("user-data-folder", "", "User data folder.")
88-
f.BoolVar(&opts.skipFeatureAutoMapping, "skip-feature-auto-mapping", false, "")
86+
f.Bool("skip-feature-auto-mapping", false, "")
8987
f.BoolVar(&opts.skipPersistCustoms, "skip-persisting-customizations-from-features", false, "")
9088
f.BoolVar(&opts.experimentalLockfile, "experimental-lockfile", false, "")
9189
f.BoolVar(&opts.experimentalFrozenLockfile, "experimental-frozen-lockfile", false, "")
@@ -580,15 +578,10 @@ func imageBuildFor(cfg *config.DevContainer, opts *buildOpts) imageBuild {
580578
}
581579

582580
func checkLegacyFeatures(feats map[string]any) error {
583-
for id := range feats {
584-
if features.ClassifyID(id) != features.SourceLegacyShorthand {
585-
continue
586-
}
587-
name := id
588-
if i := strings.LastIndexByte(id, ':'); i != -1 {
589-
name = id[:i]
590-
}
591-
if !features.IsKnownLegacyFeature(name) {
581+
userFeatures, _ := features.UpdateDeprecatedFeaturesIntoOptions(sortedUserFeatures(feats))
582+
for _, f := range userFeatures {
583+
id, _ := features.BackwardCompatibleID(f.UserFeatureID)
584+
if features.ClassifyID(id) == features.SourceLegacyShorthand {
592585
return &coreerrors.ContainerError{Description: fmt.Sprintf(msgLegacyFeature, id)}
593586
}
594587
}
@@ -751,7 +744,6 @@ func (r *buildRunner) buildCompose(ctx context.Context, cfg *config.DevContainer
751744
workspaceFolder: opts.workspaceFolder,
752745
cacheFrom: opts.cacheFrom,
753746
buildNoCache: opts.noCache,
754-
skipFeatureAutoMapping: opts.skipFeatureAutoMapping,
755747
experimentalFrozenLockfile: opts.experimentalFrozenLockfile,
756748
noLockfile: opts.noLockfile,
757749
lockfileExcludeIDs: opts.lockfileExcludeIDs,
@@ -840,7 +832,6 @@ func (r *buildRunner) featureBuildOptions(cfg *config.DevContainer, hostSub *con
840832
Push: opts.push,
841833
Output: opts.output,
842834
ContainerEnv: cfg.ContainerEnv,
843-
SkipFeatureAutoMapping: opts.skipFeatureAutoMapping,
844835
FrozenLockfile: opts.experimentalFrozenLockfile,
845836
NoLockfile: opts.noLockfile,
846837
ConfigPath: cfg.ConfigFilePath,

‎internal/cli/build_held_test.go‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -108,12 +108,12 @@ func TestImageBuildFor(t *testing.T) {
108108
}
109109

110110
func TestCheckLegacyFeatures(t *testing.T) {
111-
for _, id := range []string{"node", "node:1", "golang", "ghcr.io/devcontainers/features/node:1", "./local-feature", "owner/repo/feature"} {
111+
for _, id := range []string{"node", "golang", "gradle", "ghcr.io/devcontainers/features/node:1", "./local-feature", "owner/repo/feature"} {
112112
if err := checkLegacyFeatures(map[string]any{id: true}); err != nil {
113113
t.Errorf("%s: unexpected error %v", id, err)
114114
}
115115
}
116-
for _, id := range []string{"not-a-feature", "not-a-feature:1"} {
116+
for _, id := range []string{"not-a-feature", "not-a-feature:1", "node:1", "node:18", "gradle:1"} {
117117
err := checkLegacyFeatures(map[string]any{id: true})
118118
if err == nil || !strings.Contains(err.Error(), "Legacy feature '"+id+"' not supported") {
119119
t.Errorf("%s: error = %v, want the legacy feature error naming it", id, err)

‎internal/cli/compose_up.go‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -274,7 +274,7 @@ func (r *upRunner) composeFeatureSets(ctx context.Context, cfg *config.DevContai
274274
return nil, "", err
275275
}
276276
}
277-
res, err := fetchFeatureSetsWithOrder(ctx, r.log, cfg.Features, localFeatureRoots{filepath.Dir(cfg.ConfigFilePath), opts.workspaceFolder}, opts.skipFeatureAutoMapping, lockfile, cfg.OverrideFeatureInstallOrder)
277+
res, err := fetchFeatureSetsWithOrder(ctx, r.log, cfg.Features, localFeatureRoots{filepath.Dir(cfg.ConfigFilePath), opts.workspaceFolder}, lockfile, cfg.OverrideFeatureInstallOrder)
278278
if err != nil {
279279
return nil, "", err
280280
}

‎internal/cli/feature_deps.go‎

Lines changed: 5 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -32,7 +32,10 @@ func renderDependencyMermaid(client oci.Registry, logger log.Logger, roots []str
3232
func newMetadataProcessFeature(client oci.Registry, logger log.Logger, local localFeatureRoots, lockfile *features.Lockfile) features.ProcessFeature {
3333
return func(node *features.FNode) (*features.Set, error) {
3434
id := node.UserFeatureID
35-
srcType := features.ClassifyID(id)
35+
resolvedID, srcType, err := resolveFeatureID(logger, id)
36+
if err != nil {
37+
return nil, err
38+
}
3639

3740
switch srcType {
3841
case features.SourceLocalPath:
@@ -68,13 +71,12 @@ func newMetadataProcessFeature(client oci.Registry, logger log.Logger, local loc
6871
}, nil
6972

7073
default:
71-
resolvedID, _ := features.ResolveID(id, false)
7274
ref, err := oci.ParseRef(resolvedID)
7375
if err != nil {
7476
return nil, fmt.Errorf("ERR: Feature '%s' could not be processed. %w", id, err)
7577
}
7678
if lockfile != nil {
77-
if integrity := lockfile.Features[id].Integrity; integrity != "" {
79+
if integrity := lockfile.Features[resolvedID].Integrity; integrity != "" {
7880
if pinned, perr := oci.ParseRef(ref.Resource + "@" + integrity); perr == nil {
7981
ref = pinned
8082
}

‎internal/cli/feature_deps_held_test.go‎

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -2,9 +2,11 @@ package cli
22

33
import (
44
"bytes"
5+
"fmt"
56
"net/http"
67
"path/filepath"
78
"reflect"
9+
"slices"
810
"strings"
911
"testing"
1012

@@ -170,6 +172,34 @@ func TestMetadataProcessFeatureOCI(t *testing.T) {
170172
}
171173
}
172174

175+
func TestMetadataProcessFeatureLegacyIDs(t *testing.T) {
176+
reg := newOCIFeatureRegistry()
177+
reg.add(t, "ghcr.io/devcontainers/features/node:1", map[string]string{"devcontainer-feature.json": `{"id":"node"}`}, nil)
178+
var logged bytes.Buffer
179+
logger := log.New(log.Options{Writer: &logged, Level: log.LevelInfo})
180+
set, err := newMetadataProcessFeature(reg, logger, localFeatureRoots{}, nil)(&features.FNode{UserFeatureID: "node"})
181+
if err != nil {
182+
t.Fatal(err)
183+
}
184+
if got := set.SourceInfo.(*features.OCISource); got.Resource != "ghcr.io/devcontainers/features/node" || got.UserID != "node" {
185+
t.Errorf("source = %+v, want node:1 for the id as written", got)
186+
}
187+
if !strings.Contains(logged.String(), "(!) WARNING: Using the deprecated 'node' Feature.") {
188+
t.Errorf("log = %q, want the deprecated Feature warning", logged.String())
189+
}
190+
for _, id := range []string{"node:18", "gradle", "my-custom-feature"} {
191+
reg.fetched = nil
192+
_, err := resolveMetadata(t, reg, localFeatureRoots{}, nil, id, nil)
193+
if err == nil || err.Error() != fmt.Sprintf(msgLegacyFeature, id) || len(reg.fetched) != 0 {
194+
t.Errorf("%s: err = %v, fetched %v; want the legacy Feature error and no request", id, err, reg.fetched)
195+
}
196+
}
197+
reg.fetched = nil
198+
if _, err := resolveMetadata(t, reg, localFeatureRoots{}, nil, "owner/repo/feat", nil); err == nil || !slices.Equal(reg.fetched, []string{"owner/repo/feat:latest"}) {
199+
t.Errorf("owner/repo/feat: err = %v, fetched %v; want registry owner", err, reg.fetched)
200+
}
201+
}
202+
173203
func TestRenderDependencyMermaid(t *testing.T) {
174204
reg := newOCIFeatureRegistry()
175205
root := `{"id":"root","dependsOn":{"ghcr.io/owner/coll/dep:1":{}}}`

0 commit comments

Comments
 (0)