Рекомендации по созданию пакетов
Это руководство содержит упрощенный справочник по созданию и публикации высококачественных пакетов для авторов пакетов NuGet. Основное внимание уделяется рекомендациям по работе с пакетами, связанными с метаданными и упаковкой. Более подробные рекомендации по созданию высококачественных библиотек см. в руководстве по использованию библиотеки .NET с открытым кодом.
Типы рекомендаций
В каждой статье приводится список рекомендаций таких типов: Do, Consider, Avoid и Do not. Тип рекомендации указывает на то, насколько строго следует ее придерживаться.
Рекомендациям Do нужно следовать практически всегда. Например:
✔️ СЛЕДУЕТ включить краткое описание пакета, которое описывает его содержимое.
Рекомендациям типа РЕКОМЕНДУЕТСЯ обычно также нужно следовать, но могут быть и исключения:
✔ РЕКОМЕНДУЕТСЯ выбрать имя пакета NuGet с префиксом, который соответствует критериям резервирования префикса NuGet.
Рекомендации Avoid обычно относятся к нежелательным действиям, но иногда их можно нарушать.
❌ AVOID Ссылки на пакеты NuGet, требующие указания точной версии.
Рекомендации Do not указывают на то, чего практически никогда не следует делать.
❌ НЕ СЛЕДУЕТ использовать свойство метаданных LicenseUrl.
Создание пакета NuGet
Последний рекомендуемый способ создания пакета NuGet — на основе проекта в стиле пакета SDK. Свойства проекта в стиле пакета SDK, включая целевую платформу и метаданные пакета определяются в файле проекта.
Создайте пакет из проекта в стиле пакета SDK, определив необходимые свойства и упаковку в Visual Studio или dotnet CLI.
✔️ СЛЕДУЕТ создать проект в стиле пакета SDK и создать (упаковать) пакет с помощью Visual Studio или dotnet CLI.
Более подробные инструкции по созданию пакетов, включая необходимые клиентские средства, примеры файлов проекта и команды, см. в статье Создание пакета NuGet с помощью dotnet CLI.
Чтобы решить, на какие платформы .NET ориентироваться, ознакомьтесь с нашим последним руководством по кросс-платформенной поддержке.
Метаданные пакета
Метаданные — это базовый компонент любого пакета NuGet. Качество ваших метаданных может значительно повлиять на возможность обнаружения, удобство использования и надежность пакета.
В Visual Studio для указания метаданных пакета выберите "Проект > Свойства [имя проекта] > Пакет".
Элементы метаданных пакета также могут быть указаны непосредственно в файле проекта.
Ниже приведено сопоставление таблиц и описание доступных элементов метаданных пакета.
| Имя свойства Visual Studio | Имя файла проекта или свойства MSBuild | Имя свойства nuspec | Description |
|---|---|---|---|
Package id |
PackageId |
id |
Имя или идентификатор пакета. |
Package version |
PackageVersion |
version |
Версия пакета NuGet. |
Authors |
Authors |
authors |
Разделенный запятыми список авторов пакетов, часто с указанием имен отдельных пользователей или названия организации. |
Description |
Description |
description |
Описание пакета. |
Copyright |
Copyright |
copyright |
Сведения об авторских правах для пакета. |
Project URL |
PackageProjectUrl |
projectUrl |
URL-адрес домашней страницы проекта. |
Icon File |
PackageIcon |
icon |
Путь к файлу изображения значка пакета. |
README |
PackageReadmeFile |
readme |
Путь к файлу Markdown README пакета. |
Repository URL |
RepositoryUrl |
repository url |
URL-адрес репозитория, из которого был создан пакет. |
Repository type |
RepositoryType |
repository type |
Тип репозитория, на который указывает URL-адрес репозитория (например, git). |
Tags |
PackageTags |
tags |
Разделенный пробелами список тегов и ключевых слов для описания пакета. Теги используются при поиске пакетов. |
Release notes |
PackageReleaseNotes |
releaseNotes |
Разделенный пробелами список тегов и ключевых слов для описания пакета. |
Licensing - Expression |
PackageLicenseExpression |
license type="expression" |
Выражение лицензии SPDX. |
Licensing - File |
PackageLicenseFile |
license type="file" |
Путь к пользовательскому файлу лицензии. |
Идентификатор пакета
При публикации совершенно нового пакета:
✔️ СЛЕДУЕТ выбрать уникальный идентификатор пакета, который отличается от идентификаторов существующих пакетов на сайте NuGet.org.
Вы можете проверить, является ли идентификатор пакета уникальным, выполнив поиск идентификатора на сайте NuGet.org или проверив, существует ли следующая ссылка: https://www.nuget.org/packages/<имя пакета>.
✔ РЕКОМЕНДУЕТСЯ выбрать имя пакета NuGet с префиксом, который соответствует критериям резервирования префикса NuGet.
Резервирование идентификатора префикса для пакета позволит получить проверенную проверка метку:
Чтобы узнать больше, ознакомьтесь с документацией по резервированию префикса идентификатора пакета.
Версия пакета
✔ СЛЕДУЕТ использовать SemVer для управления версиями пакета NuGet.
По сути это означает, что используется следующий формат: основная_версия.дополнительная_версия.исправление[-предварительный_выпуск].
✔️ СЛЕДУЕТ опубликовать пакет в виде пакета предварительного выпуска, если он не является стабильным или является предварительной версией.
Дополнительные рекомендации см. в руководстве по управлению версиями библиотеки .NET.
Авторы
✔️ СЛЕДУЕТ использовать поле Author (Автор) для указания своего имени или названия организации.
Например, если имя пользователя NuGet.org — m.ivanova и вы используете "Marina Ivanova" в этом поле, пользователям будет легче распознать автора. Если имя пользователя NuGet.org для организации — ContosoToolkit, название "Contoso Corporation" так же будет более узнаваемым и внушающим доверие.
Description
✔️ СЛЕДУЕТ включить краткое описание пакета (до 4000 символов).
Описание пакета — это один из наиболее значимых блоков информации при поиске NuGet. Обычно это первое, на что обращают внимание пользователи при определении того, подходит ли им такой пакет.
Авторские права
✔️ СЛЕДУЕТ добавить в пакет уведомление об авторских правах:"Copyright (c) <имя/компания><год>".
Уведомление об авторских правах означает, что вашу работу нельзя копировать без разрешения. Включение уведомления об авторских правах в пакет — это простая операция, которая не влечет никаких последствий.
Пример: Авторское право (c) Contoso 2020
URL проекта
✔️ СЛЕДУЕТ включить ссылку на связанный проект, репозиторий или веб-сайт компании.
Сайт проекта должен предоставлять всю информацию о пакете. Обычно именно там пользователи будут искать документацию.
Icon
✔️ РЕКОМЕНДУЕТСЯ использовать значок для пакета, чтобы его можно было визуально отличить. Даже такое относительно небольшое улучшение положительно влияет на оценку пакета.
Значки могут быть разными для отдельных пакетов, а также использовать фирменную символику.
✔️ СЛЕДУЕТ использовать изображение размером 128×128 пикселей с прозрачным фоном (в формате PNG), чтобы обеспечить оптимальное отображение.
NuGet автоматически масштабирует изображение для клиента, в котором он отображается.
❌ НЕ СЛЕДУЕТ использовать устаревшее свойство метаданных IconUrl.
README
✔️ Добавьте файл markdown README, который содержит общие сведения о том, что делает ваш пакет и как приступить к работе.
Файл README пакета значительно улучшит восприятие качества пакета и подключение новых пользователей. Также рекомендуется предварительно просмотреть файл README перед отправкой. Дополнительные сведения см . в том, как включить файл README в пакет NuGet.
Тип репозитория и URL-адрес
✔ РЕКОМЕНДУЕТСЯ настроить Source Link, чтобы автоматически добавить метаданные системы управления версиями в пакет NuGet и упростить отладку библиотеки.
Source Link автоматически добавляет
Repository URLиRepository Typeв метаданные пакета. При этом также добавляется конкретная фиксация, связанная с версией пакета.
Теги
✔️ СЛЕДУЕТ включить несколько тегов с ключевыми терминами, описывающими ваш пакет, чтобы улучшить обнаружение.
Теги обрабатываются алгоритмом поиска NuGet.org и особенно полезны при наличии терминов, которые не включены в идентификатор пакета, но являются релевантными.
Например, при публикации пакета для записи строк в консоль можно включить следующее: "ведение журнала, журнал, консоль, строка, выходные данные".
Заметки о выпуске
✔️ СЛЕДУЕТ включать заметки о выпуске в каждое обновление с описанием внесенных изменений.
Хотя для заметок о выпуске не требуется специальный формат, рекомендуется включить сведения о следующем:
- Критические изменения
- Новые возможности
- Исправления ошибок
Если вы уже отслеживаете заметки о выпуске или журнал изменений в репозитории, можно также включить ссылку на соответствующий файл.
Лицензирование
✔️ СЛЕДУЕТ включить выражение лицензии или файл лицензии в пакет.
Внимание
Проект без лицензии по умолчанию предусматривает монопольное авторское право. Это означает, что вы не предоставили кому-либо разрешения на использование вашего проекта.
❌ НЕ СЛЕДУЕТ использовать устаревшее свойство метаданных LicenseUrl.
Так вы создадите юридически неоднозначную ситуацию, ведь изменения лицензии в URL-адресе приведут к изменению отображаемой лицензии для предыдущих версий пакета.
Если пакет имеет открытый код
✔️ СЛЕДУЕТ выбрать лицензию с открытым кодом, чтобы сделать пакет открытым.
"Лицензии на ПО с открытым кодом — это лицензии, которые соответствуют определению открытого кода. По сути, они позволяют свободно использовать, изменять и распространять программное обеспечение". — Open Source Initiative. Дополнительные сведения о программном обеспечении с открытым кодом и Open Source Initiative см. здесь: https://opensource.org/.
✔️ РЕКОМЕНДУЕТСЯ включить выражение лицензии в пакет.
Выражения лицензий являются наиболее понятными. Они информируют пользователей о том, могут ли они использовать ваш пакет или изменилась ли лицензия.
Примечание.
NuGet.org принимает только лицензионные выражения для лицензий, утвержденных Open Source Initiative или Free Software Foundation.
Если пакет не включает открытый код
✔️ СЛЕДУЕТ добавить файл лицензии в пакет.
В пакет можно включить любой файл лицензии (в формате TXT или MD), в том числе нестандартные лицензии.