Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Document popularity transfers #2490

Merged
merged 15 commits into from
Aug 17, 2021
Merged

Document popularity transfers #2490

Changes from all commits
Commits
Show all changes
15 commits
Select commit Hold shift + click to select a range
fd802cb
Popularity transfers doc started
Jan 15, 2021
562fee3
Update Deprecate-packages.md
chrisraygill Jul 23, 2021
4e2a3e7
Update Deprecate-packages.md
chrisraygill Jul 23, 2021
38f98b8
Work
loic-sharma Jul 23, 2021
ed2282e
Add advanced scenarios
loic-sharma Jul 23, 2021
8d4d3ec
Tweaks
loic-sharma Jul 23, 2021
e22877f
Update Deprecate-packages.md
loic-sharma Jul 23, 2021
3e4b8a8
Update Deprecate-packages.md
loic-sharma Jul 23, 2021
71bfb2b
Update Deprecate-packages.md
loic-sharma Jul 23, 2021
6436087
Update Deprecate-packages.md
loic-sharma Jul 24, 2021
6878bb7
Update Deprecate-packages.md
loic-sharma Jul 24, 2021
22d0b8b
Update Deprecate-packages.md
loic-sharma Jul 24, 2021
310a715
Update docs/nuget-org/Deprecate-packages.md
loic-sharma Jul 27, 2021
ec0fd1a
Update docs/nuget-org/Deprecate-packages.md
loic-sharma Jul 27, 2021
b6ff4f4
Update Deprecate-packages.md
loic-sharma Jul 27, 2021
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
78 changes: 78 additions & 0 deletions docs/nuget-org/Deprecate-packages.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,3 +61,81 @@ Project `My.Test.Project` has the following deprecated packages
> My.Sample.Lib 6.0.0 Legacy My.Awesome.Package

```

## Transfer popularity to a newer package

Package authors who have deprecated a legacy package can choose to transfer its "popularity" to a newer package to boost the newer package's search ranking. This helps customers discover the newer package instead of the deprecated package.

For example, let's say I have two packages:

* My deprecated legacy package, `Contoso.Legacy` with 3 million downloads
* My latest package, `Contoso.Latest` with 5 downloads

NuGet.org prefers search results with higher downloads/popularity. Given the search query "Contoso", my deprecated package `Contoso.Legacy` would likely rank above my latest package `Contoso.Latest` in search results.

To solve this problem, I can apply to transfer the popularity of my deprecated legacy package to my latest package. This would cause `Contoso.Latest` to rank higher in search results, while `Contoso.Legacy` would rank lower. Only the internal popularity scores for the packages is impacted, the actual download count for each package will not be affected.

> [!Note]
> Popularity transfers can make it significantly harder for consumers to find the legacy package.

See the table below to get a concrete idea of how a popularity transfer may impact search rankings for the query "Contoso":

| Search ranking | Before popularity transfer | After popularity transfer |
|---------------- |-------------------------------- |-------------------------------- |
| 1 | *Contoso.Legacy, 3M downloads* | *Contoso.Latest, 5 downloads* |
| 2 | Contoso.Scanner, 2M downloads | Contoso.Scanner, 2M downloads |
| 3 | Contoso.Core, 1.5M downloads | Contoso.Core, 1.5M downloads |
| 4 | Contoso.UI, 1M downloads | Contoso.UI, 1M downloads |
| ... | ... | ... |
| 20 | *Contoso.Latest, 5 downloads* | *Contoso.Legacy, 3M downloads* |

### Popularity transfer application process

1. Review the [popularity transfer requirements](#popularity-transfer-requirements).
2. Email [account@nuget.org](mailto:account@nuget.org) with the deprecated package whose popularity should be transferred, and, the list of stable package(s) that should receive the popularity transfer.

After the application is submitted, we will notify you of your application's acceptance or rejection (with the criteria that caused rejection). We may need to ask additional identifying questions to confirm owner identity.

#### Popularity transfer requirements

* The legacy packages and new packages must share all owners.
* The new packages must be clearly related to the legacy packages in naming and function (i.e. an evolution or next generation).
* All versions of the legacy packages must be deprecated and point to the new packages receiving the transfer.
* The popularity transfer must not cause confusion for NuGet users or worsen the NuGet search experience.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This stands out as important to me. Looking at the table above, I can see users being confused by their search results because the actual download counts don't match the order of popularity, leading to mistrust in the nuget.org search results.

Do we have any way of communicating to users that a package's popularity has been transferred - or that a package is special/an outlier in some way? I'm thinking in a subtle, visual way that can be seen at a glance on the search results.

Copy link
Contributor Author

@loic-sharma loic-sharma Jul 26, 2021 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Looking at the table above, I can see users being confused by their search results because the actual download counts don't match the order of popularity, leading to mistrust in the nuget.org search results.

This is an excellent question. Search looks for results that are most relevant to the user's query. Packages' popularity/downloads is one of many heuristics used to achieve this goal. In other words, it's totally fine for the top results to have low downloads as long as they are the best matches for the search query. If we simply ordered results by their downloads, packages with many downloads would always drown out packages that are most relevant to the user's query.

We did consider a visual cue but decided it wasn't necessary since we only allow popularity transfers if it improves the search results. If a customer were to complain that search results are unexpected, this would be a strong signal that we messed up and allowed a popularity transfer that regresses search rankings.

Here's an example of popularity transfers at work:

image

Notice the top two results have much fewer downloads than the third result. However, the top two results are clearly better than the third!

/cc @chgill-MSFT who drove the spec for popularity transfers

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Loic nailed the explanation exactly. The value of this feature is to actively improve search results in cases where search ranking prioritizing downloads works against the best interest of our users. If we hear a lot of negative customer feedback or see in telemetry that search has been negatively impacted - we'll iterate on the experience accordingly 🙂

* The new packages must have a stable version.
* The legacy package must not receive popularity transfers from another deprecated package.

### Advanced popularity transfer scenarios

#### Package consolidations

I can transfer the popularity of multiple deprecated packages in favor of a single new package. For example, let's say I have 3 packages:

* My first deprecated legacy package, `Contoso.Legacy1`
* My second deprecated legacy package, `Contoso.Legacy2`
* My new consolidated package, `Contoso.Latest`

After I deprecate `Contoso.Legacy1` and `Contoso.Legacy2`, I can apply to transfer their popularity to `Contoso.Latest`.

#### Package splits

A deprecated package's popularity can be transferred to, and divided among, up to 5 newer packages. This is useful if the functionality of a deprecated package has been split among multiple new packages. For example, let's say I have 3 packages:

* My deprecated legacy package, `Contoso.Legacy`
* My first new package, `Contoso.Web`
* My second new package, `Contoso.Cloud`

`Contoso.Legacy` includes both web and cloud functionality, but I decided to separate that functionality into different packages for the next generation. After I deprecate `Contoso.Legacy`, I can apply to transfer its popularity to both `Contoso.Web` and `Contoso.Cloud`.

> [!Warning]
> The transferred popularity will be split evenly between all new packages. As a result, we recommend transferring your deprecated package's popularity to as few packages as possible.

#### Popularity transfer chains

A deprecated package cannot transfer its popularity if it is already receiving popularity from another deprecated package. For example, say I have 3 packages:

* My deprecated legacy package, `Contoso.First`
* My deprecated legacy package, `Contoso.Second`
* My new package, `Contoso.Latest`

If `Contoso.First` transfers its popularity to `Contoso.Second,` then `Contoso.Second` cannot transfer its popularity to `Contoso.Latest`. Instead, we recommend transferring the popularity of both `Contoso.First` and `Contoso.Second` to `Contoso.Latest`, as per the [Package consolidations](#package-consolidations) scenario.