Поделиться через

Объявление пакетов нерекомендуемыми

  • Статья

Пакет можно объявить нерекомендуемым в случае прекращения его поддержки или перевода потребителей на использование другого пакета.

Процедура объявления пакета нерекомендуемым отличается от удаления пакета из списка.

  • При удалении пакета из списка становится невозможным его обнаружение, так как он будет скрыт в результатах поиска.
  • При объявлении пакета нерекомендуемым существующие потребители пакета могут определять его установку или использование в проектах. Кроме того, они могут узнать причину такого объявления и ознакомиться с альтернативным пакетом, предлагаемым его издателем. Пакет, объявляемый нерекомендуемым, не удаляется из списка.

Издатель может и удалить пакет из списка, и объявить его нерекомендуемым.

Процесс объявления пакета нерекомендуемым

  1. Чтобы объявить пакет нерекомендуемым, перейдите в раздел Управление пакетами и выберите Объявить нерекомендуемым.

    Go to deprecate package option

  2. Выберите версию, которую нужно объявить нерекомендуемой. Чтобы объявить нерекомендуемыми все версии, выберите параметр Выбрать все версии.

    Select package versions to deprecate

  3. Выберите причину объявления пакета нерекомендуемым. Если пакет больше не поддерживается, выберите параметр Устаревший. Если в конкретной версии присутствует критическая ошибка, выберите параметр содержит критические ошибки. Для любой другой причины выберите Другое. Издатель всегда может указать альтернативный рекомендуемый пакет (и версию) и добавить настраиваемое сообщение для владельцев.

    Select reasons alternate package recommendation and custom message

Примечание

Настраиваемые сообщения отображаются только на сайте nuget.org. Из клиентов они не выводятся. Сейчас настраиваемые сообщения недоступны в таких клиентах, как dotnet.exe и диспетчер пакетов NuGet.

Клиентский интерфейс для нерекомендуемых пакетов

После того как пакет объявляется нерекомендуемым, его потребители будут уведомлены об этом следующими способами (в зависимости от используемого клиента).

Visual Studio

Доступно начиная с Visual Studio 2019 версии 16.3

В Visual Studio предупреждение об использовании нерекомендуемого пакета выводится на вкладке Installed. В нем отображается предупреждение для пакета и приводятся сведения об объявлении его нерекомендуемым (включая причину этого объявления и данные об альтернативном пакете, который можно использовать вместо него, если таковой имеется).

Deprecated packages on Visual Studio installed tab of package manager

dotnet.exe

Доступно начиная с пакета SDK для .NET 3.0

Если вы используете dotnet.exe, в папке решения или проекта можно выполнить команду dotnet list package --deprecated для получения списка нерекомендуемых пакетов и сведений об объявлении их нерекомендуемыми.

> dotnet list package --deprecated

The following sources were used:
   https://api.nuget.org/v3/index.json

Project `My.Test.Project` has the following deprecated packages
   [netcoreapp3.0]:
   Top-level Package      Resolved   Reason(s)   Alternative
   > My.Sample.Lib        6.0.0      Legacy      My.Awesome.Package

Перенос популярности в более новый пакет

Авторы пакетов, у которых имеется устаревший пакет, могут перенести "популярность" в более новый пакет, чтобы повысить рейтинг пакета при поиске. Это помогает клиентам обнаружить более новый пакет, а не устаревший пакет.

Например, предположим, что у меня есть два пакета:

  • Устаревший пакет Contoso.Legacy был загружен 3 миллиона раз
  • Последний пакет Contoso.Latest был загружен всего 5 раз

NuGet.org предпочитает результаты поиска с более высоким показателем загрузки/популярности. При вводе поискового запроса "Contoso" устаревший пакет Contoso.Legacy, скорее всего, будет стоять в рейтинге выше последнего пакета Contoso.Latest в результатах поиска.

Чтобы решить эту проблему, я могу перенести популярность устаревшего пакета на последний пакет. Это приведет к тому, что у Contoso.Latest будет более высокий рейтинг в результатах поиска, а у Contoso.Legacy он будет более низким. Это влияет только на внутренние оценки популярности для пакетов, тогда как фактическое число скачиваний для каждого пакета не будет затронуто.

Примечание

Перенос популярности может значительно усложнить для потребителей поиск устаревшего пакета.

См. таблицу ниже, чтобы понять, как перенос популярности может повлиять на рейтинг в результатах поиска по запросу "Contoso":

Рейтинг в результатах поиска Перед переносом популярности После переноса популярности
1 Contoso.Legacy, 3 млн скачиваний Contoso.Latest, 5 скачиваний
2 Contoso.Scanner, 2 млн скачиваний Contoso.Scanner, 2 млн скачиваний
3 Contoso.Core, 1,5 млн скачиваний Contoso.Core, 1,5 млн скачиваний
4 Contoso.UI, 1 млн скачиваний Contoso.UI, 1 млн скачиваний
... ... ...
20 Contoso.Latest, 5 скачиваний Contoso.Legacy, 3 млн скачиваний

Процесс переноса популярности

  1. Ознакомьтесь с требованиями к переносу популярности.
  2. Отправьте сообщение электронной почты на адрес account@nuget.org с устаревшим пакетом, популярность которого следует перенести, а также со списком стабильных пакетов, которые должны получать популярность.

После отправки приложения мы уведомим вас о принятии или отклонении приложения (с условиями, вызвавшими отклонение). Для подтверждения личности владельца мы можем попросить вас ответить на несколько дополнительных вопросов.

Требования к переносу популярности

  • Все владельцы устаревших и новых пакетов должны быть одинаковыми.
  • Новые пакеты должны быть четко связаны с устаревшими пакетами в именовании и функции (т. е. в эволюции или следующем поколении).
  • Все версии устаревших пакетов должны быть устаревшими и указывать на новые пакеты для переноса.
  • Перенос популярности не должен вызывать путаницы для пользователей NuGet или ухудшить поиск NuGet.
  • Новые пакеты должны иметь стабильную версию.
  • Устаревший пакет не должен принимать перенос популярности из другого устаревшего пакета.

Сложные сценарии переноса популярности

Консолидации пакетов

Я могу перенести популярность нескольких устаревших пакетов в один новый пакет. Например, предположим, что у меня есть три пакета:

  • Первый устаревший пакет, Contoso.Legacy1
  • Второй устаревший пакет, Contoso.Legacy2
  • Новый консолидированный пакет, Contoso.Latest

После того как я признаю Contoso.Legacy1 и Contoso.Legacy2 устаревшими, я могу передать популярность в Contoso.Latest.

Разбиения пакета

Популярность устаревшего пакета может быть передана и разделена между новыми пакетами (до 5 пакетов). Это полезно, если функциональные возможности устаревшего пакета были разделены между несколькими новыми пакетами. Например, предположим, что у меня есть три пакета:

  • Первый устаревший пакет, Contoso.Legacy
  • Первый новый пакет, Contoso.Web
  • Второй новый пакет, Contoso.Cloud

Contoso.Legacy включает как веб-, так и облачные функции, но я решил разделить эту функциональность на разные пакеты для следующего поколения. После того как я признаю Contoso.Legacy устаревшим, я могу передать популярность в Contoso.Web и Contoso.Cloud.

Предупреждение

Перенесенная популярность будет равномерно распределена между всеми новыми пакетами. В результате мы рекомендуем переносить популярность устаревшего пакета в как можно меньшее число пакетов.

Цепочки переносов популярности

Для устаревшего пакета невозможно передать популярность, если он уже получает популярность от другого устаревшего пакета. Например, предположим, что у меня есть три пакета:

  • Первый устаревший пакет, Contoso.First
  • Второй устаревший пакет, Contoso.Second
  • Новый пакет, Contoso.Latest

Если Contoso.First передает популярность пакету Contoso.Second,, то пакет Contoso.Second не может передать свою популярность пакету Contoso.Latest. Вместо этого рекомендуется передать популярность Contoso.First и Contoso.Second пакету Contoso.Latest, что соответствует сценарию консолидации пакетов.