Add End-of-Life (EOL) Status for NuGet Packages #13598
There are no files selected for viewing
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,110 @@ | ||
| # End-of-life (EOL) packages and package lifecycle | ||
| <!-- Replace `Title` with an appropriate title for your design --> | ||
|
|
||
| - [Jon Douglas](https://github.com/jondouglas) <!-- GitHub username link --> | ||
| - [#9638](https://github.com/NuGet/NuGetGallery/issues/9638), [#9837](https://github.com/NuGet/NuGetGallery/issues/9837) <!-- GitHub Issue link --> | ||
|
|
||
| ## Summary | ||
|
|
||
| <!-- One-paragraph description of the proposal. --> | ||
| Today, there exists two major package status mechanisms for understanding if a package is [vulnerable](https://learn.microsoft.com/en-us/nuget/concepts/auditing-packages) and/or [deprecated](https://learn.microsoft.com/en-us/nuget/nuget-org/deprecate-packages). | ||
|
|
||
| Recently, the NuGet team has shipped functionality allowing package authors to include markdown READMEs to contain a hodgepodge of information relating to the package such as installation instructions, getting started examples, contributing tips, and less often seen is how the package is supported through an official or unofficial support policy. | ||
|
|
||
| To make these package statuses clearer to package consumers and authors, this proposal introduces a new concept to indicate when a package has reached the end of its intended life. | ||
|
|
||
| The reason being is that the current package statuses mean specific things today and how they are perceived such as: | ||
|
|
||
| - Vulnerable - Indicates the package has a known security vulnerability registered in an official CVE database. | ||
| - Deprecated - Indicates the package is deprecated, meaning that people should consider migrating off of the package for a common reason such as it is **legacy, included critical bugs, or any other reason** the maintainer wants to disclose. These packages are no longer recommended to use but may still receive updates. | ||
|
|
||
| Introducing a concept of **"end of life"** will make it clear to package authors that these packages are not intended to be used any further as they are no longer supported, will not receive critical updates, and feedback will not be considered. This would be a new definition including: | ||
|
|
||
| - End of life (EOL) - Indicates the package is no longer maintained, supported, or updated by its authors. | ||
|
|
||
| | Status | Definition | Updates Available | User Guidance | Risk | | ||
| |-------------|-----------------------------------------|-------------------|----------------------------------------|----------| | ||
| | EOL | No longer maintained or supported | No | Migrate to alternatives | High | | ||
| | Vulnerable | Contains known security vulnerabilities | Possibly | Update or find secure alternatives | High | | ||
|
There was a problem hiding this comment. For the Vulnerable status, we need to clarify this Risk value is different than the Severity value of the associated CVE. Example here where the CVE has a severity of moderate: There was a problem hiding this comment. Yeah these are separate categories of risk and relative to the policy of the consumer. I was just trying to convey the idea that Vulnerable and EOL risk is high compared to other package statuses. |
||
| | Deprecated | Not recommended for use | Possibly | Transition to newer packages | Moderate | | ||
|
There was a problem hiding this comment. According to https://learn.microsoft.com/en-us/nuget/nuget-org/deprecate-packages The "long description" of the legacy deprecation message is "this package is legacy and is no longer maintained". Therefore, it appears to me that you're adding a new way to do the same thing. I'm also concerned that even if you intend that deprecate and EOL have different definitions as per the spec, that few people read the docs and in everyday language, deprecated and end of life effectively mean the same thing making it a bit confusing. There was a problem hiding this comment. We absolutely do not want to re-invent the wheel here. But I do want to share how people perceive this and our current data (I'll add it into the spec as well): Here is a quick pulse survey over the last day on how people perceive it as is: 
As for data, deprecated w/ legacy is the leading "reason". 
I believe we may need to find a clear separation and better flow for these package statuses so they do not come as a surprise to developers. A natural flow might be marking a package deprecated for a specific reason and after a specific timeframe, to mark it end of life to encourage people further to migrate. I think Levi's comment above touches upon providing users a deprecation window before a package is then EOL'd. There was a problem hiding this comment. I can't help coming back to Andy's point: how is Deprecated different from EOL? Would the workflow on https://learn.microsoft.com/en-us/nuget/nuget-org/deprecate-packages be any different for EOL (other than not needing a reason)? And how does this proposal address the motivations differently from the Deprecated status, other than by exposing the state more forcefully in the client? My main concern is that many of these proposed changes create an implied distinction that EOL is a terminal state, but Deprecated is not (contrary to how it is defined today). Summarizing and addressing the Motivations:
To me, the biggest potential value I see proposed here is
However, this seems like "We want to change the deprecation experience, without changing it in situ", but in doing so creates a lot of ambiguity. Is there a concrete scenario that isn't already somehow addressed by Deprecated? There was a problem hiding this comment. The core question here is whether the ecosystem has evolved to the point where it needs clearer definitions for these two states:
I do not see this as a technology problem (i.e. does the technology/capabilities exist, yes, they do), but rather a matter of what definitions people would prefer to see and how they would be emphasized. There was a problem hiding this comment. Is there a demand for the limited future support state? (Not doubting, just asking if there's data.) In my limited experience, I've seen planned EOLs ("not supported after {date}"), but never encountered a package with the 3-phase lifecycle described below in the spec ( There was a problem hiding this comment. Yep, this ask represents various growing pains of 1P libraries we manage across .NET, Azure, etc. I've also invited other groups to read through this and express their thoughts/pains! The challenges here is that deprecation today does not encourage the urgency warranted (their words that I also share) and we need to bring more awareness to when packages are deprecated / end of life. There's a huge shift in security best practices going on and this is a good time to dive into this question further I believe! There was a problem hiding this comment.
This statement defines a slightly different problem: when deprecation is signaled, it isn't being treated as an urgent priority. Would that be addressed by escalating how deprecation is represented to end users? E.g. if we change from "warning" iconography to "error" iconography (as you've described for EOL), would it make deprecated packages seem more urgent? There was a problem hiding this comment. There's a lot to unpack in this topic! But yes, it could be treated differently if we did certain things! That is definitely an option here. i.e. treat deprecation marked as legacy differently. There was a problem hiding this comment. The new EOL state is a good idea, since we're currently overloading the deprecated state to mean two things. Currently, when we want to move an Azure SDK to an EOL state, we have to maintain it for 3 years. During that period, the library is 'deprecated' but still supported. Once those three years are up, we'd like to EOL it, but we're relying on custom messages added to the 'deprecated' state to convey this. The process would be more crisply defined with a separate EOL state we could apply to packages that are outside that 3 year window. |
||
|
|
||
| ## Motivation | ||
|
|
||
| <!-- Why are we doing this? What pain points does this solve? What is the expected outcome? --> | ||
|
|
||
| There are two primary motivations in doing this work. The first being a direct answer to the "am I supported?" question. This is especially prevalent in the .NET ecosystem due to many first-party package providers have robust support policies that require a developer to understand with a decoder ring and too much time on their hands. It should be explictly simple to know you're supported in your current solution so long as your packages do not report EOL. | ||
|
There was a problem hiding this comment.
I don't know what this term means. Are there both first-party and third-party package providers? Perhaps use just "package providers"? |
||
|
|
||
| The second primary motivation is security. Being on unsupported packages that are EOL is a high risk as there will be no security updates and may render your application vulnerable. A typical lifecycle of an end of life package may accrue known vulnerabilities over the years as they are discovered which may add additional risk for developer teams to sincerely consider prompt remediation. | ||
|
There was a problem hiding this comment. I feel like this is still a maintainability consideration. |
||
|
|
||
| The expected outcome would be developers having a clear package status for knowing if a package in their package graph is "supported" or not through its status being EOL. EOL packages tend to be very difficult for engineering teams to build in the first place to provide security updates and typically aren't serviced do to the difficulty. | ||
|
|
||
| ## Explanation | ||
|
|
||
| ### Functional explanation | ||
|
|
||
| <!-- Explain the proposal as if it were already implemented and you're teaching it to another person. --> | ||
| <!-- Introduce new concepts, functional designs with real life examples, and low-fidelity mockups or pseudocode to show how this proposal would look. --> | ||
| This functionality will follow the footsteps of the existing deprecation and vulnerability functionality. It will be closest to the deprecation experience today, but will include a way for a package owner to mark a package and its many versions at anytime "EOL". There will be no reason nor custom message to provide to users. However, there will be an suggested alternate package to use to encourage a direct action from the developer. | ||
|
There was a problem hiding this comment. It's unclear to me, does this mean that EOL is intended to be defined at a package ID and therefore apply to all versions of a package, or is EOL like deprecation where each version can be independently togged EOL/not-EOL? There was a problem hiding this comment. If EOL, possible to have "Recommended" alternatives? There was a problem hiding this comment.
Defined similarly to deprecation at the per-version level.
Yes, suggested alternatives are utilized today and EOL could suggest new versions of the same package or another package ID + version entirely. There was a problem hiding this comment.
In that case, I think we need to have more of a think of the technical considerations and what the acceptable perf impact will be for the part of this spec that says we should warn at restore time. I get that this is intended to be a CX spec, or non-technical spec, but given the similarily to NuGetAudit and vulnerability reporting, we already know information that is relevant. For NuGetAudit, the 90th percentile for loading the vulnerability database is 500 milliseconds, the 95th percentile is 1.4 seconds, and the 99th percentile is over 5.5 seconds. We already know that deprecation data on nuget.org is at least an order of magnitude larger than the amount of vulnerability data, so we can expect that the customers already having bad performance to have a much worse time if we add EOL and deprecation warnings at restore time. The VS perf team also say that our vulnerability database is causing measurable impact on memory usage. This is of course something that can be solved/improved before this new EOL (or deprecation warnings during restore) is implemented. But I want to make it clear that it's not a simple case of "do it the same way that NuGetAudit does vulnerabilities". We have to find a better approach for implementation. If EOL information was only at the package ID level, not specific versions, yes it will be less useful to package authors who want to only support specific branches (major/minor versions), but it will be much more technically feasible from a performance point of view. There was a problem hiding this comment. I wonder if we're leaning in the https://xkcd.com/927/ direction. If I read the docs and read about deprecation first and then EOL later, I feel like I'd have questions about which one to use in which scenario. We should aim to simplify that decision. There was a problem hiding this comment. I also echo Andy's concerns about the technical considerations for this. There was a problem hiding this comment. We (Azure SDK team) need a way to convey extra information to users via a custom message for EOL packages. Specifically, we often provide migration guides for users to follow when moving off the deprecated/EOL package to the recommended replacement. We're currently providing that information via a custom message. |
||
|
|
||
| When a package is marked EOL, a few things will happen: | ||
|
|
||
| - The package at restore time will appear with a new warning letting any consumers know the package is EOL. | ||
|
There was a problem hiding this comment. As a default behavior, a warning may suffice. I can imagine some customers wanting package restoration of EOL packages to produce errors instead, to force breaking of builds. There was a problem hiding this comment. These warnings tend to break people due to them enabling TreatWarningsAsErrors, but definitely agreed it should suffice. |
||
| - The package on NuGet.org and throughout browsing experiences will show a label or affordance mentioning its EOL status. | ||
| - The package on NuGet.org API can be queried for the EOL package status for any tooling to build upon this. | ||
| - The dotnet CLI will have a list command to show all EOL packages. | ||
|
There was a problem hiding this comment. How can we accommodate customers who want to suppress the display of EOL packages from the configured package feeds? It could be a nice way to prevent installation of them. Imagine a nuget.config file placed at the root of the project repository with a setting that enables this behavior. Any dev working on that project won't see EOL packages when browsing configured package feeds. There was a problem hiding this comment. Ideally they can just disable auditing type flags within their project similar to what vulnerability provides today |
||
|
|
||
| A new visual icon will be used to encourage a user to "stop" using an EOL package. A stop sign or a crossed circle concept should suffice(i.e. `StatusStopped`), highlighting the need for immediate action. | ||
|
|
||
| Given that this can be either an extension of the existing deprecation functionality or its own standalone functionality, the only major con of extending today is adding more reasons and status which can dilute the intention of a package's lifecycle such as: | ||
|
|
||
| Package created -> package deprecated -> package end of life | ||
|
|
||
| A standalone feature also allows for more tailored experiences in the future without being constrained to the existing deprecation framework. As needs evolve for end of life, features can be easily adapted and extended. | ||
|
|
||
| ### Technical explanation | ||
|
|
||
| <!-- Explain the proposal in sufficient detail with implementation details, interaction models, and clarification of corner cases. --> | ||
|
|
||
| ## Drawbacks | ||
|
|
||
| <!-- Why should we not do this? --> | ||
| It could be argued that it really isn't the package manager's job to designate whether or not a package is supported by the current maintainer. Rather that it is the responsibility of the maintainer to be in close contact with their community to help them understand how their products are supported, such as NuGet packages. | ||
|
|
||
| Of course one of the major drawbacks will be having a clear differentiation of each of these package statuses. There is a clear need to provide this, and perhaps this could be a good precedent to provide for package maintainers in an end-to-end fashion of a package's life. | ||
|
|
||
| On the telemetry side, packages that are EOL but still are used heavily may be an indicator of lacking an alternative and may need further investigation. | ||
|
|
||
| ## Rationale and alternatives | ||
|
|
||
| <!-- Why is this the best design compared to other designs? --> | ||
| <!-- What other designs have been considered and why weren't they chosen? --> | ||
| <!-- What is the impact of not doing this? --> | ||
| Having a central place for marking a package end of life can be a huge quality of life upgrade, especially in the current climate we live in where NuGet can now provide warnings at restore time for vulnerabilities, [deprecations in the future](https://github.com/NuGet/Home/issues/13266), and potentially this. | ||
|
|
||
| The current alternatives exist today and are utilized. Many packages provide their support policies through package READMEs or as resources on their project's website. They use the deprecation feature with various reasons to communicate with their users regarding the package's current status. | ||
|
|
||
| ## Prior Art | ||
|
|
||
| <!-- What prior art, both good and bad are related to this proposal? --> | ||
| <!-- Do other features exist in other ecosystems and what experience have their community had? --> | ||
| <!-- What lessons from other communities can we learn from? --> | ||
| <!-- Are there any resources that are relevant to this proposal? --> | ||
|
|
||
| There exists many ecosystems with deprecation concepts, but to my knowledge and research I have not found one that includes this EOL concept. | ||
|
|
||
| ## Unresolved Questions | ||
|
|
||
| <!-- What parts of the proposal do you expect to resolve before this gets accepted? --> | ||
| <!-- What parts of the proposal need to be resolved before the proposal is stabilized? --> | ||
| <!-- What related issues would you consider out of scope for this proposal but can be addressed in the future? --> | ||
| - Is this a unique enough experience to consider being a standalone package status? | ||
| - Is end of life (EOL) the proper terminology? | ||
|
There was a problem hiding this comment. That is a tricky question and was also commented by @zivkan above. On my first reading of this I didn't think "Deprecated" and "EOL" were distinct concepts, and then after I realised they are, I thought the terminology was problematic because the words themselves don't innately have different meanings that you can assume people will understand. Either one of them might be assumed to come earlier in the lifecycle than the other, or they might be assumed to mean the same thing. However I don't immediately have a better suggestion. I thought of "Withdrawn" or "DoNotUse" but they both need clarification too. Perhaps if the clients show some kind of "What does this mean?" link next to any non-good status, and that goes to a page depicting the lifecycle, that would be understandable enough. There was a problem hiding this comment. Someone suggested a "traffic light" metaphor which I really liked: 🟢 Green: No status or issues. The package is safe to use. Of course, these policies are entirely up to the consumer, but a mental model to use to demonstrate the "lifecycle" and what this proposal hopes to help define further. There was a problem hiding this comment. Here's a doc I like on EOL. It's more about communication in general, but provides insight into how we might need to communicate the topics being discussed here. |
||
|
|
||
| ## Future Possibilities | ||
|
|
||
| <!-- What future possibilities can you think of that this proposal would help with? --> | ||
| - Integration with security tools to automatically flag EOL packages in dependency graphs. | ||
|
There was a problem hiding this comment. Is Dependabot one such security tool to look at? What about generating Component Governance alerts too? There was a problem hiding this comment. Yep, this metadata could absolutely be used by whatever tooling to help users understand their risk. |
||
| - Enhanced UI features on NuGet.org and in development tools to better highlight EOL packages. | ||
| - Tools to suggest or automate migration from EOL packages to supported alternatives. | ||
| - Future enhancements to manage package lifecycle stages, including pre-release, stable, deprecated, and EOL. | ||
| - Enable community-driven support for EOL packages where maintainers have abandoned projects but the community wishes to continue support. | ||
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
The difference between "no longer maintained" and "updated by its authors" isn't super clear to me. I suggest instead using your previous wording of "no longer supported, will not receive critical updates, and feedback will not be considered".