Основные сведения о Git и GitHub для документации по Microsoft Learn

  • Статья

Общие сведения

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

Git — это система управления версиями с открытым исходным кодом. Она упрощает совместную работу над проектами такого типа с помощью распределенной системы управления версиями файлов, которые хранятся в репозиториях. По сути, Git позволяет интегрировать в определенный репозиторий потоки работы, выполненные несколькими участниками в течение определенного времени.

GitHub — это веб-служба размещения для репозиториев Git, например тех, которые используются для хранения содержимого Microsoft Learn . В GitHub размещается основной репозиторий всех проектов. Из этого репозитория участники копируют свою работу.

Git

Если вы знакомы с централизованными системами управления версиями (например, Team Foundation Server, SharePoint или Visual SourceSafe), вы заметите, что Git использует уникальный рабочий процесс и специальную терминологию для поддержки распределенной модели. Например, в Git не блокируются файлы, как это обычно бывает, когда файл берут на редактирование или возвращают после редактирования. На самом деле Git учитывает изменения на более тонком уровне, сравнивая файлы байт за байтом.

Git также использует многоуровневую структуру для хранения содержимого проекта и управления им.

  • Репозиторий — это единица хранения самого высокого уровня. Репозиторий содержит одну или несколько ветвей.
  • Ветвь — это единица хранения с текущими файлами и папками, которые формируют содержимое проекта. Ветви используются для разделения потоков работы (обычно они называются версиями). Участники всегда вносят изменения в содержимое в определенной ветви, и эти изменения привязаны к соответствующей ветви. Все репозитории содержат ветвь по умолчанию (обычно она называется главной, "main") и одну или несколько ветвей, предназначенных для объединения с ветвью по умолчанию. Ветвь по умолчанию является текущей версией и "единственным истинно верным источником" для определенного проекта. Из этой родительской ветви создаются все остальные ветви в репозитории.

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

  • Для локального взаимодействия участники используют такие инструменты, как консоль Git Bash, которая поддерживает команды Git для управления локальными репозиториями и обмена данными с репозиториями GitHub.
  • Кроме того, участники используют сайт www.github.com с интегрированной системой Git для управления согласованием изменений, возвращаемых обратно в основной репозиторий.

GitHub

Примечание

Хотя руководство по документации основано на использовании GitHub, некоторые команды используют Visual Studio Team Services для размещения репозиториев Git. Клиент Visual Studio Team Explorer — это графический интерфейс для взаимодействия с репозиториями Team Services. Этот интерфейс является альтернативой использованию команд Git в командной строке.
Кроме того, многие приведенные ниже руководства разработаны в качестве рекомендаций, которые появились в результате многолетнего размещения содержимого служб Azure в GitHub. Они могут потребоваться в некоторых репозиториях Microsoft Learn.

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

Организация каталогов

Как упоминалось ранее, ветвь по умолчанию выступает в качестве текущей версии содержимого проекта. Содержимое ветвь по умолчанию и ветвей, созданных на его основе, слабо согласуется с организацией статей на соответствующих страницах Microsoft Learn. Подкаталоги используются для разделения содержимого (например, служб), мультимедийного содержимого (например, файлов изображений) и файлов include, которые позволяют повторно использовать содержимое.

Основной каталог articles обычно находится в корне репозитория. Этот каталог статей содержит набор подкаталогов. Статьи в подкаталогах форматируются в виде файлов Markdown, использующих расширение MD. Некоторые репозитории, которые поддерживают несколько служб, например репозиторий Azure-Docs, используют универсальный подкаталог /articles. Другие репозитории, например IntuneDocs, используют подкаталог, который называется как служба: /IntuneDocs.

В корне этого каталога находятся общие статьи, которые описывают службу или продукт в целом. Как правило, каталог содержит еще одну серию подкаталогов, которые соответствуют функциям и службам или распространенным сценариям. Например, статьи, которые описывают службу виртуальных машин Azure, находятся в подкаталоге /virtual-machines, статьи "Изучение вопроса" службы Intune размещены в подкаталоге /understand-explore.

Подкаталог Media

В каждом каталоге находится подкаталог /media для соответствующих файлов мультимедиа. Файлы мультимедиа содержат изображения, используемые в статьях со ссылками на изображения.

Подкаталог includes

Содержимое для многократного использования, которое является общим для двух или нескольких статей, помещается в подкаталог /includes основного каталога articles. В файле Markdown, где используется включаемый файл, соответствующее расширение Markdown include помещается в расположение, на которое должна указывать ссылка на включаемый файл.

Дополнительные рекомендации см. в разделе Справочник по разметке Markdown — Включаемые файлы.

Шаблон файла Markdown

Для удобства в корневом каталоге каждого репозитория обычно находится файл шаблона Markdown с именем template.md. Его можно использовать как начальный файл для создания статьи с последующей отправкой в репозиторий. Файл содержит следующие компоненты.

  • Заголовок метаданных в верхней части файла, разделенный двумя строками с тремя дефисами. Он содержит различные теги, используемые для отслеживания информации, относящейся к статье. Метаданные статьи обеспечивают дополнительные возможности. Например, можно указать ссылки на автора и участника, настроить строку навигации, добавить описание статьи. Они также включают оптимизацию для поисковых систем и процессы создания отчетов, которые корпорация Майкрософт использует для оценки производительности содержимого. Как видите, метаданные имеют большое значение.
  • Раздел метаданных с описанием различных тегов и значений метаданных. Если вы не знаете, какие значения нужно использовать для раздела метаданных, их можно оставить пустыми или закомментировать с помощью начального хэштега (#). Так рецензент запроса на вытягивание в репозитории сможет проверить или выполнить их.
  • Различные примеры использования разметки Markdown для форматирования элементов статьи.
  • Общие инструкции по использованию расширений разметки Markdown, которые можно применить для различных типов оповещений.
  • Примеры встраивания видео с помощью iframe.
  • Общие инструкции по использованию расширений технической документации Майкрософт, которые можно применять для специальных элементов управления, таких как кнопки и селекторы.

Запросы на вытягивание

Запрос на вытягивание — используя этот удобный способ, участник предлагает набор изменений для внесения в стандартную ветвь. Изменения (они также называются фиксациями) хранятся в ветви участника. GitHub использует их для моделирования результатов их объединения со стандартной ветвью. Запрос на вытягивание также служит механизмом для предоставления участнику отзыва рецензента запроса. Рецензент отправляет участнику отзыв после процесса сборки и проверки, чтобы решить потенциальные проблемы или вопросы до того, как изменения будут объединены в стандартной ветви.

Существует два способа работы с запросом на вытягивание в зависимости от размера изменений, которые вы хотите предложить. Дополнительные сведения см. в статье Рабочий процесс для участников GitHub: незначительные или эпизодические изменения.