Внесение основных изменений в документацию По Microsoft Learn

Важно!

Все репозитории, которые публикуются в Microsoft Learn, приняли либо Microsoft Open Source Code of Conduct, либо .NET Foundation Code of Conduct. Дополнительные сведения см. в разделе Часто задаваемые вопросы по правилам поведения. С любыми вопросами и комментариями можно также обратиться по адресу opencode@microsoft.com или conduct@dotnetfoundation.org.

Незначительные исправления или пояснения к примерам документации и кода в общедоступных репозиториях охватываются условиями использования learn.microsoft.com. Любые изменения будут генерировать комментарий в запросе на вытягивание, запрашивая отправку лицензионного соглашения об онлайн-вкладе (CLA), если вы не являетесь сотрудником Корпорации Майкрософт. Вам нужно заполнить онлайн-форму перед обработкой запроса на вытягивание.

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

Ниже представлены примеры таких изменений.

• Внесение значительного вклада. Например, ваши вклады (дополнения, изменения или удаления) могут охватывать несколько статей и должны быть зафиксированы и проверены как одна единица работы в одном PR.
• Создание и публикация новой статьи; здесь, как правило, требуется более надежный локальный редактор.
• Добавление новых образов или обновление изображений, которые обычно требуют одновременно создания подкаталога media , создания файлов изображений, обновления ссылок на изображения в статьях и предварительного просмотра файлов Markdown в локальном редакторе для тестирования отрисовки изображений.
• Обновление статьи через определенный период времени перед публикацией. В этих случаях обычно требуется регулярно интегрировать другие изменения, происходящие в ветви по умолчанию. Это можно легко сделать с помощью Git Bash и локального редактирования. Вы также рискуете потерять изменения, если вы сделаете это через веб-редактор GitHub и подождите, прежде чем зафиксировать изменения.
• Внесение постоянных обновлений в ту же статью после открытия PR. Хотя вы можете использовать веб-редактор GitHub для этой цели, вы можете создать несколько невыполненных PR для одного файла, который может конфликтовить друг с другом.

Необходимые компоненты

• Определите репозиторий GitHub, в который хранится документация, которую вы хотите изменить.
• Создайте учетную запись GitHub, если у вас нет учетной записи.
• Установите средства Git и Markdown.
• Настройте локальный репозиторий Git.
• Просмотрите основы Git и GitHub (необязательно).

Создание и проверка рабочей ветви

Чтобы начать, создайте рабочую ветвь в локальном репозитории для записи предлагаемых изменений. Дополнительные сведения о ветвях см. в основах Git и GitHub.

В этом руководстве используется Git Bash и Visual Studio Code, но вы можете использовать любой клиент и редактор Git.

1. В VS Code откройте папку репозитория локального клона. В меню "Файл" выберите "Открыть папку" и перейдите к папке на компьютере.

2. Выберите "Вид " в верхнем меню и выберите "Терминал ", чтобы открыть интегрированный терминал.

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

4. Прежде чем создать рабочую ветвь, убедитесь, что локальная основная ветвь находится в актуальном состоянии со всем в главной ветви репозитория. Эта задача гарантирует, что рабочая ветвь фиксирует все изменения, которые произошли в рабочем репозитории с момента последнего синхронизации с ним.

   1. Перейдите в основную ветвь в локальном репозитории:

      git checkout main 
      

   2. Убедитесь, что локальная основная ветвь является текущей:

      git pull upstream main 
      

5. Создайте локальную рабочую ветвь на основе основной:

   git checkout -b <branch-name>
   

   <branch-name> — заполнитель, При выполнении команды замените его уникальным и значимым именем для ветви и удалите угловые скобки.

6. Отправьте локальную рабочую ветвь в удаленную ветвь в вилке GitHub:

   git push origin <branch-name> -u
   

   Параметр -u связывает локальные и удаленные ветви. Этот параметр позволяет отправлять фиксации в вилку, вводя только git push вместо git push origin <branch-name>него.

Поиск исходного файла Markdown

Чтобы изменить статью, найдите исходный файл статьи в клоне локального репозитория. В VS Code получите доступ к файлам Markdown репозитория через проводник (значок документа в левой верхней боковой панели). В проводнике показана структура папок репозитория, и вы можете перейти к файлу, который требуется изменить.

Если файл не удается найти, посетите статью в Microsoft Learn и щелкните значок "Изменить карандаш". Расположение относительной папки в репозитории GitHub отображается в URL-адресе. Ниже приведен пример URL-адреса ссылки "Изменить ":

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Ниже приведен пример расположения файла для этого URL-адреса.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Измените файл .

1. Откройте файл в VS Code, выбрав его.
2. Внесите нужные изменения.
3. Сохраните изменения, выбрав Файл>Сохранить. Используйте команду "Сохранить все" для одновременного сохранения нескольких файлов.

Фиксация и отправка изменений

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

Вы можете использовать терминал VS Code или пользовательский интерфейс VS Code для фиксации и отправки изменений.

Терминал VS Code

1. git status Выполните команду, чтобы убедиться, что в списке измененных файлов отображаются только измененные файлы.

   git status
   

2. git add Выполните команду, за которой следует путь к файлу и имя файла, чтобы выполнить этап изменения файла.

   git add folder-name/file-name.md
   

   Если вы изменили несколько файлов, введите git add команду для каждого файла.

   Кроме того, можно запустить git add . (заметить период после add) для автоматического этапа всех внесенных изменений. Этот метод быстрее, но может вызвать проблемы, включив изменения, внесенные в результате аварии.

3. Запустите git status еще раз, чтобы подтвердить, какие изменения были выполнены.

4. git commit Выполните команду, за которой следует сообщение фиксации, чтобы сохранить изменения в локальном клонированного репозитория.

   git commit -m "your commit message"
   

5. Запустите git push , чтобы отправить изменения.

   git push
   

Пользовательский интерфейс VS Code

Вы можете создать и отправить фиксацию с помощью функций интеграции Git VS Code. Не забудьте продолжить работу на одном компьютере. Если вы переключаете компьютеры, у вас нет последней версии рабочей ветви для продолжения работы.

1. Убедитесь, что локальный репозиторий по-прежнему имеет ту же рабочую ветвь, проверка. В пользовательском интерфейсе VS Code в левом нижнем углу отображается ветвь. Имя ветви также работает в качестве кнопки для переключения ветвей.

   

2. На левой боковой панели VS Code выберите средство "Вилка", чтобы увидеть панель "Управление версиями" Git .

   

   Измененный файл отображается в разделе "Изменения " с помощью M справа, чтобы указать, что он был изменен. Новые файлы отображаются с U (без отслеживания), а удаленные файлы отображаются с D.

3. Этап изменений. Наведите указатель мыши на строку "Изменения" , пока не + появится значок. Выберите этот значок. Это действие эквивалентно команде git add . Теперь файл отображается в разделе "Поэтапное изменение ".

4. Введите сообщение фиксации, например "дата обновления метаданных" в текстовом поле "Сообщение" и выберите проверка марк.

   

5. Отправка фиксации. Нажмите кнопку "Синхронизировать изменения ", которая отображается под блоком фиксации сообщения.

   

Готово! Теперь код находится в репозитории GitHub и готов к открытию PR.

Нужно исправить уже отправленные изменения? Это просто! Просто повторите описанные выше шаги, начиная с редактирования файла, чтобы внести изменения в ту же ветвь, а затем зафиксировать и отправить еще раз (нет необходимости задавать сервер вышестоящий на последующих отправках той же ветви). Как правило, ветви используются для разделения потоков работы, поэтому вам не нужно создавать новую ветвь, если вы не готовы работать над чем-то другим.

Внесите следующее изменение

Готовы внести другое изменение, не связанное с этим? Вернитесь к ветвь по умолчанию, извлеките из репозитория вышестоящий, чтобы обновить вилку и проверка новую ветвь. Выполните следующие команды в Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

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

Следующие шаги

• Если вы выполнили описанные выше действия, теперь пришло время открыть pr , чтобы объединить изменения в основную ветвь.
• Дополнительные сведения о таких разделах, как синтаксис расширений Markdown и Markdown, см. в справочнике Markdown.