Support package renames
Status: Abandoned
Author: Loïc Sharma
The work for this feature and the discussion for this spec are tracked here - NuGetGallery#7896
Package popularity strongly influences search rankings on NuGet.org. When you want to change the name of your package, you need to create a new package. This new package starts with no popularity and has to compete and likely underperforms against the older package. This leads to poor search quality for the new package.
For example, the following popular packages have been renamed:
Today, package authors can "rename" a package by deprecating it and adding a suggested alternative. In fact, packages like Fake and NuGet.Packaging.Core have done exactly just that. This approach has a few flaws:
-
Package deprecations does not affect search results. For example, the package
FAKEis deprecated and suggestsfake-clias an alternative, however, searching for "FAKE" yieldsFAKEas the first result andfake-clias the thirteenth result. -
Package deprecations are version specific. In other words, the author must deprecate each version of their package to effectively "rename" it. Furthermore, keeping deprecation messages consistent across many versions can be tricky. For example, notice how
NuGet.Packaging.Corehas inconsistent deprecations across versions5.3.0and5.4.0.
- Add a "Rename" section to the "Manage Package" page
- Update the "Deprecation" section on the "Manage Package" page
- Show package renames on the "Display Package" page
- Popularity Transfers
- Visual Studio (Preview)
- .NET Core CLI (Preview)
We will add a new section to the "Manage Package" page that lets the package's owners link the current package to its replacements:
Clicking on the Learn more link will lead you to a documentation page detailing explaining how to "rename" a package. The documentation will also explain the transfer popularity feature.
You can select any package as the New package that is different from the current package as long as it has at least one listed and non-deleted version. Furthermore, the New package may be a package owned by a different account.
The Provide custom message field is a free-form field to give consumers more context on the package rename. This field is not required.
Selecting Transfer popularity will split the popularity of the current package and transfer it equally to the new packages (more on that in the next section). As a result, the new packages will now be favored in search rankings over the replaced package. Given transferring the popularity "hurts" the current package's search rankings, a warning message is displayed if a Transfer popularity checkbox is selected.
We will only allow up to 5 new packages. Once you reach the limit, the + Add more link will disappear:
Saving will notify the user that it may take several hours for this change to propagate through our system:
Opening the "Rename" section will show a message if popularity transfers are pending:
We will add a rename a package link to the "Deprecation" section:
Clicking on this link will scroll down to the "Rename" section and expand it.
Once you've marked your package as renamed, the "Display Package" page will notify consumers:
If you chose a single New package, the message on the "Display Package" page will read: This package has been renamed.
If you choose multiple New packages, the message on the "Display Package" page will read: This package has been renamed or split into new packages.
NOTE: This message only appears on the old package that was renamed. The new packages' "Display Package" page won't say anything!
Below the Additional Details section is the free-form text provided by the package author. If no text was provided, the Additional Details section will be hidden.
Today, packages receive a popularity score based off their total downloads. These popularity scores influence search rankings: a package with a higher popularity score is more likely to be a top result.
Renamed packages will transfer a percentage of their downloads equally between the replacements that have Transfer Popularity checked. In other words, the replacement packages will have increased popularity scores. On the other hand, the renamed package will have a decreased popularity score. This transfer only affects popularity scoring, NuGet.org and Visual Studio will display packages' original downloads.
NOTE: A package with both outgoing and incoming transfers will "ignore" the incoming downloads. The transferred incoming downloads are effectively lost.
Visual Studio's search rankings will reflect popularity transfers due to package renames. For now, package renames information will NOT appear in Visual Studio. This will be added in the future.
NOTE: The mock-ups below capture our vision for the experience on Visual Studio. These are early previews and may change!
Customers should be notified that the package they are browsing has been renamed:
Customers should be notified that a package they have installed has been renamed:
The "Installed" tab will have an "Info" icon if an installed package has been renamed. This will be replaced by a "Warning" icon if an installed package is deprecated.
An "Info" icon will be added to the renamed package in the list of installed packages. This will be replaced by a "Warning" icon if the renamed package is also deprecated.
The details pane on the right side displays the rename information. A package that is both renamed and deprecated will show the deprecated message first, followed by the renamed message.
Customers should be notified that a package with updates has been renamed:
An "Info" icon will be added to the renamed package in the list of package updates. This will be replaced by a "Warning" icon if the renamed package is also deprecated.
The details pane on the right side displays the rename information. A package that is both renamed and deprecated will show the deprecated message first, followed by the renamed message.
For now, package renames information will NOT appear in the .NET Core CLI. We will consider adding a --renamed option to the dotnet list package command.
If you have feedback, feel free to reach out in the following ways:
- GitHub on NuGetGallery#7896
- Twitter at @sharmaloic