How to deprecate a Dev Container Feature in a git repository? (and remove the Feature from the metadata?)

[eitsupi]

We had to deprecate some Dev Container Features.

• [just] Deprecated in favor of ghcr.io/guiyomh/features/just eitsupi/devcontainer-features#30
• fix(fish): Remove fish feature from metadata guiyomh/features#17

I did this by creating a directory deprecated in the repository and moving the source code from the src directory.

It would be great if such a method could be documented and standardized.

[joshspicer]

Great timing! @samruddhikhandale has opened a new spec issue to add a deprecatedIds property to the devcontainer-feature.json to solve issues like this. Please let us know on that issue your thoughts.

[eitsupi]

Oh, I did not expect to be able to use deprecatedIds for this purpose. That sounds nice!

If we specify their own id as follows, this Feature would need to be removed from the repository's metadata and devcontainers index.

{
  "id": "foo",
  "deprecatedId": [
    "foo"
  ]
}

[samruddhikhandale]

In the spec issue, I was trying to use deprecatedId for renaming an existing Feature 🤔
So that anyone referencing the old Feature will still be able to install that Feature without breaking their configs.

I believe you are simply trying to deprecate a Feature?

If we specify their own id as follows, this Feature would need to be removed from the repository's metadata and devcontainers index.

devcontainers index - Moving the source folder of the Feature out of the src folder (or even deleting the folder) will avoid adding the metadata to devcontainer-collection.json . We build the index daily, hence in max 24 hours, the Feature will vanish from the index which is then consumed by https://containers.dev/features and VS Code.

repository's metadata - We could simply delete the OCI artifact in this case?

Feature --> Package settings

[eitsupi]

devcontainers index - Moving the source folder of the Feature out of the src folder (or even deleting the folder) will avoid adding the metadata to devcontainer-collection.json . We build the index daily, hence in max 24 hours, the Feature will vanish from the index which is then consumed by containers.dev/features and VS Code.

Yes, so I did it as I wrote at the beginning of this issue.
Since it was not my intention to make the package itself uninstallable, I simply moved the source code and ran the release workflow.

My suggestion is that such a step be documented (the name of the directory to be moved to be defined) or that deprecatedIds be made available for this use.

[samruddhikhandale]

My suggestion is that such a step be documented (the name of the directory to be moved to be defined)

Makes sense. I'll document this part, thanks 👍

or that deprecatedIds be made available for this use.

I somehow think that this might complicate the property and the source folder will continue to exist. So documenting on how to clean up should be the best move forward?

[joshspicer]

If the intention is that a user wants to abandon maintaining a Feature, but not actually delete the current published artifacts, we might want to do additional work here

Perhaps actually introduce a deprecated flag that the action will append to the collection metadata if a Feature is removed from the ./src directory. Supporting tools (our index, etc...) can surface helpful information with that property.

Right now the action just concatenates all the individual devcontainer-feature.json, although the published index file does have more properties (like majorVersion).

[eitsupi]

In the future, when the CLI automatically generates the top-level README for the repository, it would be great if it could also generate a section on deprecated Features.

To do this, we need to tell the CLI which features have been deprecated. (I was assuming it would be a specific subdirectory, e.g. /deprecated)

[samruddhikhandale]

@eitsupi Based on the discussion in this issue, updated the spec to add a new isDeprecated property. Would appreciate your thoughts/feedbacks on the approach on that spec issue. Thanks!

[eitsupi]

I think #146 seems good, thank you for working on this.

Once this is implemented I will use this to deprecate some Features.

[eitsupi]

The new deprecated property is working well now. So I am closing this issue.
https://github.com/eitsupi/devcontainer-features/blob/af60bc8a47c03d97971a1effd9631ef7f1f3bd97/src/just/devcontainer-feature.json#L5

Thank you for working on this series of tasks.