New feature: Deprecated packages

Hi, all. Tidelift engineer John here. Every so often, a package you’re working on just doesn’t cut it anymore. You want to (or have to) rename it or move it under a new organization. A large package gets split into multiple small packages. Or, in the worst cases, it’s become actively harmful to continue to use an old package. At that point, you need to deprecate the old package.

Some ecosystems have the concept of officially deprecating a package, and two of those, NPM and Packagist, publish that information in an easy-to-parse format. If you’re publishing a package on those ecosystems and mark the whole package as deprecated via that ecosystem’s mechanism, it’s now picked up by Libraries.io automatically:

But other ecosystems don’t support this, or their support is limited and can’t describe a lot of the situations under which a package gets deprecated and what a subscriber can do about its use. That’s why we now have deprecated package support in Tidelift. At the bottom of a package page, active lifters will see:

This new feature allows us to support a lot of the common requests we’ve received from lifters, and some of the edge cases that we’ve seen or run into as developers ourselves:

  • How can I rename a package, and keep lifting the old one while subscribers transition?
  • How can I let subscribers know they should stop using a package completely?
  • How can I guide subscribers on an often-skipped transition to alternative packages?

When you deprecate a package on Tidelift, you have the option of selecting a deprecation type. We typically see package deprecations phrased as “use this other package for x, y, z reasons”, and, more rarely, “don’t use this package at all”, and you can indicate to subscribers your intent for deprecation with this setting. You also get a markdown-enabled text field to help explain to subscribers any other instructions or reasons for the change:

Finally, you can provide the ecosystem and name of a package that subscribers should move to instead. Right now, we’re only autocompleting the names of packages you’re lifting, but you can enter in any valid package to redirect subscribers to:

And, for those using NPM and Packagist, most deprecation settings are automatically passed down from Libraries.io to Tidelift, so subscribers will know right away to be ready for more information about your decision.

This feature is still new and fresh, and we’d love to hear your feedback on it. Thanks!

1 Like

Is nuget deprecation supported? https://docs.microsoft.com/en-us/nuget/nuget-org/deprecate-packages

@SimonCropp Not yet. In order to pull full-package deprecation info from Nuget via the API, we need to request not only the package registration information:

curl https://api.nuget.org/v3/registration3/e2e.deprecated.191015.183921.8640468/index.json | jq '.items[0].items[0] | {"catalog @id": .catalogEntry."@id" }

{
  "catalog @id": "https://api.nuget.org/v3/catalog0/data/2019.10.15.18.43.43/e2e.deprecated.191015.183921.8640468.1.0.0.json"
}

but for each version of the package, we need to request each .catalogEntry.@id and get the deprecation info for each version:

curl https://api.nuget.org/v3/catalog0/data/2019.10.15.18.43.43/e2e.deprecated.191015.183921.8640468.1.0.0.json | jq '{ "deprecation": .deprecation }'

{
  "deprecation": {
    "@id": "https://api.nuget.org/v3/catalog0/data/2019.10.15.18.43.43/e2e.deprecated.191015.183921.8640468.1.0.0.json#deprecation",
    "alternatePackage": {
      "@id": "https://api.nuget.org/v3/catalog0/data/2019.10.15.18.43.43/e2e.deprecated.191015.183921.8640468.1.0.0.json#deprecation/alternatePackage",
      "id": "BaseTestPackage",
      "range": "[1.0.0, )"
    },
    "message": "This is an end-to-end test!",
    "reasons": [
      "Other",
      "Legacy",
      "CriticalBugs"
    ]
  }
}

It wasn’t worth the effort at the current time to do that because of the overhead of making and tracking all of the requests per package, but it’s something we’d definitely like to add eventually.

Is it possible for the community to mark a package as deprecated when it’s not lifted?

I’m particularly thinking of Python’s “nose” test runner: it’s not marked as deprecated on the package manager, only in the docs, but it hasn’t had release in five years. PyPI page, docs, tidelift page. It’s also incompatible with Python 3.9, which will be out around October 2020.

Meanwhile the maintainers have moved to “nose2”, which… really hasn’t been adopted at all - compare nose downloads to nose2 - 150k/day vs 8k/day is no competition.

@Zac-HD The simplest way to get a package marked as deprecated in both Libraries.io and Tidelift is to make a suggestion to the package. Every package on Libraries.io has a link to Make a suggestion:

Screenshot_20200210_083905

When you go there (and log in as needed), you’ll be able to suggest a new status for the package and offer notes/reasons for the change:

Screenshot_20200210_084007

Then we’ll be able to review that information and change it in Libraries, which will then mark it deprecated on Tidelift.

To tackle the problem from the other end, I don’t think PyPI supports whole-package deprecation beyond showing a post-install warning, which is also the level of support that RubyGems has. I could only find information on NPM, Packagist, and NuGet during my research. I would personally love to see more package managers officially support deprecation flags, if only to give regular users of the systems more urgency to switch to newer, better supported packages.

1 Like

As a meta-suggestion then, it would be great to show the package status on the libraries.io page, and to define each of the statuses!

I knew that there was the suggestions link for each package, but did not know that packages had a status - and the difference between deprecated and unmaintained may vary considerably between communities. Are all unmaintained libraries deprecated? If a library is unmaintained but the authors recommend using alternatives, should it be marked unmaintained or deprecated? etc.

Since I usually use npm’s facility to deprecate my npm packages, but it seems like Tidelift offers more metadata I could fill out; is/could there be a page for me to see all my current deprecations, and give me the opportunity to flesh out that extra metadata?

@ljharb This is also still rough as you’ll see, but if you go to your list of Packages, the ones that are deprecated (either by you or from Libraries) will have an icon next to them:

Screenshot_20200218_090603

You can’t filter or sort on them, and there’s no distinction between you having deprecated it or it being done automatically, but those are things we can definitely look into for the next pass on this feature.

For npm specifically, it’s also possible to get the deprecation message for each version from the API and pass one of those on to Tidelift (since we only do whole-package deprecation at the moment), but that also got pushed back due to time.

@Zac-HD We do show the package status on Libraries, and give a brief blurb once you click into the package, but we don’t describe the different statuses on the Suggestions page, and we can take a look into that as well. As for distinctions of terminology between communities and how we should handle that…that’s a tough one, to be sure. :slightly_smiling_face:

1 Like

The most common case, though, is that older versions are deprecated, and the newest one is not. The packages list shows the latest version, so I don’t think it makes much sense to (only/primarily) show the info there - i’d expect it on its own tab.

As for fetching the info from npm, i have a package for that :-p https://npmjs.com/deprecations

@ljharb thank you, that’s great feedback. We’ll continue to refine this task, so any thoughts on how we can improve is :sparkles:!

2 Likes