Участие в репозиториях документации по .NET

Статья
08/10/2023

Благодарим вас за проявленный интерес к процессу участия в разработке документации по .NET!

В этом документе рассказывается, как участвовать в написании статей и примеров кода, размещенных на сайте документации по .NET. Это могут быть простые действия по исправлению опечаток или сложная процедура написания статьей.

Сайт документации по .NET построен из нескольких репозиториев. Это только некоторые из них:

Процесс вклада

Шаг 1. Если вы хотите написать новое содержимое или тщательно пересмотреть существующее содержимое, откройте проблему , описывающую то, что вы хотите сделать. Содержимое в папке документов организовано в разделы, которые отражаются в оглавлении (TOC). Определите расположение раздела в Содержании. Получите отзыв по своему предложению.

–или–

Выберите существующую проблему и устраните ее. Изучите список открытых проблем и работайте над теми, которые вас интересуют.

Выполните фильтрацию по метке good-first-issue, чтобы выбрать хорошие проблемы для начинающих.
Выполните фильтрацию по метке up-for-grabs, чтобы выбрать проблемы, требующие вклада сообщества. Для этих проблем обычно требуется минимальный контекст.
Опытные участники могут работать с любыми проблемами.

Когда вы найдете нужную проблему, спросите в комментариях, открыта ли она.

Выбрав задачу для работы, создайте учетную запись GitHub и перейдите к шагу 2.

Шаг 2. Вилку репозитория /dotnet/docs (или любого репозитория, к которому вы вносите вклад) при необходимости и создайте ветвь для изменений.

Сведения о небольших изменениях см. в разделе "Изменить" в браузере.

Шаг 3. Внесите изменения в новую ветвь.

Если вы затрагиваете новую тему, этот файл шаблона будет хорошей отправной точкой. Он содержит рекомендации по написанию статьи, а также пояснения по необходимым для каждой статьи метаданным, таким как сведения об авторе. Дополнительные сведения о синтаксисе Markdown, используемом в содержимом Microsoft Learn, см . в справочнике по Markdown.

Перейдите в папку, соответствующую расположению TOC, определенному для статьи на шаге 1. В этой папке содержатся файлы Markdown для всех статей в этом разделе. При необходимости создайте папку для размещения файлов содержимого. Основная статья этого раздела называется index.md.

Для изображений и других статических ресурсов создайте подпапку с именем media, если она еще не создана, в папке, которая содержит вашу статью. В папке media создайте подпапку с именем статьи (за исключением файла индекса). Дополнительные сведения о том, где нужно разместить файлы, см. в разделе Пример структуры папок.

Не включайте встроенный код в статью, если только вы не демонстрируете конструкцию, которая не компилируется. Вместо этого используйте проект с фрагментами кода и включите код с помощью расширения кода. Это гарантирует, что пример кода будет проверен нашей системой CI.

Для фрагментов кода создайте внутри папки с вашей статьей подпапку snippets, если последняя еще не существует. В папке snippets создайте вложенную папку с именем статьи. Чаще всего вам будут нужны фрагменты кода для всех трех основных языков .NET, то есть C#, F# и Visual Basic. В этом случае для каждого из трех проектов создайте подпапки csharp, fsharp и vb. Если вы создаете фрагмент кода для статьи в папке docs/csharp, docs/fsharp или docs/visual-basic, он будет написан только на одном языке, поэтому подпапку языка можно опустить. Дополнительные сведения о том, где нужно разместить файлы, см. в разделе Пример структуры папок.

Фрагменты кода — это специальные небольшие примеры кода для иллюстрации понятий, описываемых в статье. Более крупные программы, предназначенные для скачивания и самостоятельного изучения, должны находиться в репозитории dotnet/samples. Полные примеры описаны в разделе Участие в создании примеров.

Шаг 4. Отправка запроса на вытягивание (PR) из ветви в ветвь по умолчанию.

Важно!

Функция автоматизации комментариев пока не доступна в репозиториях документации по .NET. Члены команды документации по .NET рассмотрят ваши запросы на вытягивание и выполнят слияние.

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

Если ваш запрос на вытягивание исправляет существующую проблему, добавьте ключевое слово Fixes #Issue_Number в описание запроса на вытягивание. Таким образом проблема автоматически закрывается при слиянии запроса на вытягивание. Дополнительные сведения см. в разделе Связывание запроса на вытягивание с проблемой с помощью ключевого слова.

Команда .NET рассмотрит запрос на вытягивание и сообщит, требуются ли для утверждения другие обновления или изменения.

Шаг 5. Внесите необходимые изменения в ветвь в соответствии с указаниями команды.

Наши специалисты объединят ваш запрос на вытягивание с ветвью по умолчанию, когда вы учтете их замечания и изменения будут одобрены.

Мы регулярно отправляем все фиксации из ветви по умолчанию в активную ветвь, где вы сможете непосредственно увидеть свой вклад в документацию по .NET. Обычно мы публикуем изменения ежедневно в течение рабочей недели.

Пример структуры папок

docs
  /about
  /core
    /porting
      porting-overview.md
      /media
        /porting-overview
          portability_report.png
        /shared ...
      /snippets
        /porting-overview
          /csharp
            porting.csproj
            porting-overview.cs
            Program.cs
          /fsharp
            porting.fsproj
            porting-overview.fs
            Program.fs
          /vb
            porting.vbproj
            porting-overview.vb
            Program.vb
        /shared
          /csharp ...
          /fsharp ...
          /vb ...

Примечание.

Папки языка в фрагментах кода не нужны в тех частях руководств, где предполагается использование только одного языка. Например, в руководстве по C# предполагается, что все фрагменты кода написаны на языке C#.

Показанная выше структура включает одно изображение (portability_report.png) и три проекта с фрагментами кода из статьи porting-overview.md.

Папка snippets/shared используется для фрагментов кода, которые могут охватывать несколько статей в одной и той же родительской папке, например в папке porting в предыдущем примере. Используйте папку shared, только если у вас есть веская причина, например код XAML, на который ссылается несколько статей, но который нельзя скомпилировать в папке для конкретной статьи.

Файлы мультимедиа также могут совместно использоваться в нескольких статьях, если эти статьи находятся в одной и той же родительской папке, например в папке porting в предыдущем примере. Эту папку shared использовать не рекомендуется. Используйте ее только тогда, когда это оправдано. Например, для совместного использования общего экрана загрузки для демонстрируемого приложения или диалоговых окон Visual Studio, которые приводятся в нескольких статьях.

Важно!

Как сложилось исторически, многие включенные фрагменты кода хранятся в папке /samples репозитория dotnet/docs. Если вы вносите в статью существенные изменения, следует перенести эти фрагменты в новую структуру. Однако для небольших изменений переносить фрагменты не стоит.

Участие в разработке примеров

Используемый в наших материалах код подразделяется на следующие варианты.

Примеры: читатели могут скачивать и выполнять примеры. Все примеры должны представлять собой завершенные приложения или библиотеки. Там, где пример создает библиотеку, он должен включать модульные тесты или приложение, которое позволяет читателям выполнять код. Часто они используют несколько технологий, функций или инструментов. Файл readme.md для каждого примера ссылается на статью, чтобы можно было узнать больше о понятиях, приведенных в примерах.
Фрагменты кода: иллюстрируют концепции меньшего размера или задачи. Они выполняют сборку, но не являются полными предложениями. Они будут запускаться, но не являются примерами приложения для типичного сценария. Они должны быть как можно меньше, чтобы иллюстрировать только одну концепцию или функцию. Это должен быть максимум один экран кода.

Примеры хранятся в репозитории dotnet/samples. Мы работаем над моделью, в которой структура папки примеров соответствует структуре папки документации. Мы следуем таким стандартам:

Соответствие папок верхнего уровня структуре репозитория docs. Например, в репозитории docs есть папка machine-learning/tutorials, а примеры для руководств по машинному обучению находятся в папке samples/machine-learning/tutorials.

Кроме того, все примеры в папках core и standard должны создаваться и выполняться на всех платформах, поддерживаемых .NET Core. Наша система сборки непрерывной интеграции обеспечит это. Папка framework верхнего уровня содержит примеры, которые создаются и проверяются только в Windows.

Примеры проектов должны компилироваться и запускаться на самом широком наборе платформ, возможном для конкретного примера. На практике это означает сборку консольных приложений на базе .NET Core по возможности. Примеры, относящиеся к веб-платформе или платформе пользовательского интерфейса, должны добавлять эти инструменты при необходимости. Примеры включают веб-приложения, мобильные приложения, приложения WPF или WinForms и т. д.

Мы работаем над системой непрерывной интеграции для всего кода. Если вы обновляете примеры, убедитесь, что каждое обновление является частью компилируемого проекта. В идеале следует добавить тесты для проверки примеров.

Каждый созданный вами полный пример должен содержать файл readme.md. В этом файле должно содержаться краткое описание примера (один или два абзаца). В вашем файле readme.md должно быть указано, что читатели узнают, когда изучат этот пример. Файл readme.md также должен содержать ссылку на динамический документ на сайте документации по .NET. Чтобы определить, где данный файл в репозитории сопоставлен с этим сайтом, замените /docs в пути к репозиторию на https://learn.microsoft.com/dotnet.

Ваш раздел также будет содержать ссылки на пример. Разместите ссылки непосредственно на папку с примером на сайте GitHub.

Написание нового примера

Примеры — это полные программы и библиотеки, предназначенные для скачивания. Они могут иметь небольшую область применения, но они иллюстрируют определенные понятия и могут использоваться для самостоятельного изучения и экспериментов. Чтобы читатели могли скачивать и изучать примеры, для последних действуют определенные рекомендации. Ознакомиться с рекомендациями можно на примерах для Parallel LINQ (PLINQ).

Ваш пример должен быть частью компилируемого проекта. По возможности проекты должны компилироваться на всех платформах, поддерживаемых .NET Core. Исключения — примеры, демонстрирующие возможности или инструменты определенной платформы.
Пример должен соответствовать стилю кодирования среды выполнения, чтобы не нарушать единообразие.

Кроме того, мы предпочитаем использовать методы static вместо методов экземпляра при демонстрации кода, который не требует создание экземпляра нового объекта.
Ваш пример должен включать надлежащую обработку исключений. Он должен обрабатывать все исключения, которые могут возникнуть в контексте примера. Пример, который вызывает метод Console.ReadLine для извлечения входных данных пользователя, должен использовать надлежащую обработку исключений при передаче входной строки в качестве аргумента в метод. Если пример ожидает сбой вызова метода, он должен обрабатывать полученное исключение. Всегда обрабатывайте конкретные исключения, вызываемые методом, а не исключения базового класса, например Exception или SystemException.

Создание примера:

Отправьте проблему или напишите комментарий к существующей и сообщите, что вы над ней работаете.
Напишите статью, объясняющую концепции, показанные в вашем примере (например: docs/standard/linq/where-clause.md).
Напишите свой пример (пример: WhereClause-Sample1.cs).
Создайте файл Program.cs с главной точкой входа, которая вызывает ваши примеры. Если она уже есть, добавьте вызов к вашему примеру:
```
public class Program
{
    public void Main(string[] args)
    {
        WhereClause1.QuerySyntaxExample();

        // Add the method syntax as an example.
        WhereClause1.MethodSyntaxExample();
    }
}
```

Вы создаете любой фрагмент кода или пример .NET с помощью .NET CLI, который можно установить с помощью пакета SDK для .NET. Сборка и запуск примера

Перейдите в папку примера и выполните сборку для проверки ошибок:
```
dotnet build
```
Запустите пример:
```
dotnet run
```
Добавьте файл readme.md в корневой каталог примера.

Он должен содержать краткое описание кода и ссылку на статью, к которой относится пример. Вверху readme.md должны быть метаданные, необходимые для обозревателя примеров кода. Блок заголовка должен содержать следующие поля:
```
---
name: "really cool sample"
description: "Learn everything about this really cool sample."
page_type: sample
languages:
  - csharp
  - fsharp
  - vbnet
products:
  - dotnet-core
  - dotnet
  - dotnet-standard
  - aspnet
  - aspnet-core
  - ef-core
---
```
- Коллекция languages должна включать только те языки, которые доступны для вашего примера.
- Коллекция products должна включать только относящиеся к вашему примеру продукты.

За исключением указанных случаев, все примеры создаются из командной строки на любой платформе, поддерживаемой .NET. Некоторые примеры относятся к Visual Studio и требуют Visual Studio 2017 или более поздней версии. Кроме того, некоторые примеры демонстрируют функции конкретной платформы и требуют эту платформу. Другие примеры и фрагменты кода требуют .NET Framework и запускаются на платформах Windows, и им понадобится пакет разработчика для требуемой версии .NET Framework.

Интерактивный интерфейс C#

Во всех фрагментах кода, включенных в статью, язык исходного кода указывается с помощью тега языка. Короткие фрагменты кода на C# могут содержать тег языка csharp-interactive, чтобы указать, что фрагменты кода на C# выполняются в браузере. (Для встроенных фрагментов кода используйте тег csharp-interactive. Чтобы указать на фрагменты, включенные из источника, используйте тег code-csharp-interactive.) В этих фрагментах кода отображается окно кода и окно выходных данных в статье. В окне выходных данных отображается результат выполнения интерактивного кода после запуска пользователем фрагмента кода.

Интерактивное выполнение кода C# меняет подход к работе с фрагментами кода. Читатели могут запустить фрагмент кода, чтобы увидеть результаты. Определить, должен ли фрагмент кода или соответствующий текст содержать информацию о выходных данных, можно по нескольким факторам.

Когда следует отображать ожидаемые выходные данные без запуска фрагмента кода

Предназначенные для начинающих статьи должны предоставлять выходные данные так, чтобы читатели могли сравнить свои выходные данные и ожидаемые.
Фрагменты кода, в которых выходные данные являются неотъемлемой частью статьи, должны отображать эти выходные данные. Например, в статьях о форматировании текста отформатированный текст должен отображаться без запуска фрагмента кода.
Если фрагмент кода и ожидаемые выходные данные занимают мало места, можно показать выходные данные. Это немного сохраняет время.
В статье, поясняющей, как текущий язык и региональные параметры или инвариантные язык и региональные параметры влияют на выходные данные, должно содержаться объяснение ожидаемых выходных данных. Интерактивная среда REPL (Read Evaluate Print Loop) выполняется на узле под управлением Linux. По умолчанию язык и региональные параметры, а также инвариантные язык и региональные параметры создают различные выходные данные в разных операционных системах и компьютерах. Статья должна объяснять выходные данные в системах Windows, Linux и Mac.

Когда следует исключать ожидаемые выходные данные из фрагмента кода

Если выходные данные фрагмента кода имеют большой размер, их не следует включать в комментарии. Они затрудняют понимание кода после запуска фрагмента кода.
Если фрагмент кода в статье демонстрирует тему, но выходные данные не обязательны для ее понимания. Например, код, который выполняет запрос LINQ для описания синтаксиса запроса, а затем отображает каждый элемент в коллекции выходных данных.

Примечание.

Вы можете заметить, что сейчас не все статьи соответствуют представленным здесь рекомендациям. Мы работаем над обеспечением согласованности в рамках всего сайта. Ознакомьтесь со списком нерешенных вопросов, над которыми мы работаем, чтобы решить эту конкретную задачу.

Участие в содержимом, отличном от английского языка

Предложения по улучшению содержимого с машинным переводом (MT) сейчас не принимаются. В целях улучшения качества материалов MT мы перешли на систему нейронного машинного перевода. Мы принимаем и поощряем работу над материалами, переводимыми людьми (HT), которые будем использовать для обучения системы нейронного машинного перевода. Со временем вклад в материалы НТ улучшит качество как HT, так и MT. Разделы с MT будут иметь примечание о том, что часть их содержимого может использовать машинный перевод. В этих разделах не будет отображаться кнопка Изменить, так как их редактирование отключено.

Примечание.

В большинстве локализованных документов не предусмотрена возможность оставлять или изменять отзывы с помощью GitHub. Чтобы предоставить отзыв о локализованном содержимом, используйте https://aka.ms/provide-feedback форму.

Лицензионное соглашение с участником

Перед введением запроса на вытягивание нужно подписать Лицензионное соглашение с участником (CLA) .NET Foundation. Это нужно сделать всего один раз для проектов в .NET Foundation. Дополнительные сведения о Лицензионных соглашениях с участником (CLA) см. в Википедии.

Соглашение: .NET Foundation Contributor License Agreement (CLA).

Вам не нужно подписывать соглашение заранее. Вы можете клонировать запрос на включение внесенных изменений, сделать его вилку и отправить как обычно. После создания запроса на включение внесенных изменений он классифицируется ботом CLA. Если изменение незначительное (например, вы исправили опечатку), запрос на вытягивание помечается тегом cla-not-required. В противном случае добавляется отметка cla-required. После подписания Лицензионного соглашения с участником текущие и будущие запросы на вытягивание получают отметку cla-signed.

Участие в репозиториях документации по .NET

Рекомендации по участию

Процесс вклада

Пример структуры папок

Участие в разработке примеров

Написание нового примера

Интерактивный интерфейс C#

Когда следует отображать ожидаемые выходные данные без запуска фрагмента кода

Когда следует исключать ожидаемые выходные данные из фрагмента кода

Участие в содержимом, отличном от английского языка

Лицензионное соглашение с участником

Обратная связь

Обратная связь

Дополнительные ресурсы