Support package renames

Status: Reviewing

Author: Loïc Sharma

Issue

The work for this feature and the discussion around the spec is tracked here - NuGetGallery#7896

Problem Background

NuGet.org's search rankings is heavily influenced by packages' popularity. This leads to poor search quality when a popular package is renamed.

For example, here are popular packages that have been renamed:

Package	Replacements
FAKE	fake-cli
iTextSharp	itext7
Microsoft.Tpl.Dataflow	System.Threading.Tasks.Dataflow
Microsoft.SourceLink.Vsts.Git	Microsoft.SourceLink.AzureRepos.Git
EntityFramework.Extended	Z.EntityFramework.Plus.EFCore, Z.EntityFramework.Plus.EF6
ManagedEsent	Microsoft.Database.ManagedEsent
NuGet.Packaging.Core	NuGet.Packaging

What about package deprecation?

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:

1. Package deprecations does not affect search results. For example, the package FAKE is deprecated and suggests fake-cli as an alternative, however, searching for "FAKE" yields FAKE as the first result and fake-cli as the thirteenth result.
2. 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.Core has inconsistent deprecations across versions 5.3.0 and 5.4.0.

Solution

• Add a "Rename" section to the "Manage Package" page
  • Saving renames
  • Pending renames
• Update the "Deprecation" section on the "Manage Package" page
• Show package renames on the "Display Package" page
• Popularity Transfers
• Visual Studio

Add a "Rename" section to the "Manage Package" page

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 renames

Saving will notify the user that it may take several hours for this change to propagate through our system:

Pending renames

Opening the "Rename" section will show a message if popularity transfers are pending:

Update the "Deprecation" section on the "Manage Package" page

We will add a link to the "Deprecation" section:

Clicking on this link will scroll down to the "Rename" section and expand it.

Show package renames on the "Display Package" page

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 renamed package. 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.

Popularity Transfers

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

Visual Studio's search rankings will reflect popularity transfers due to package renames. However, package renames information will NOT appear in Visual studio. This will be added in the future.

Feedback

If you have feedback, feel free to reach out in the following ways:

• GitHub on NuGetGallery#7896
• Twitter at @sharmaloic