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

  • Статья

Обзор

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

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

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

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

Ветвь

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

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

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

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

Вилка

Этот термин обычно используется в качестве существительного при ссылке на копию основного репозитория GitHub. Фактически вилка — это просто другой репозиторий. Особенностью вилки является то, что GitHub поддерживает ее подключение к основному (родительскому) репозиторию. Этот термин иногда используется в качестве команды, как в разделе "Сначала необходимо вилку репозитория".

Git

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

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

  • Репозиторий — это единица хранения самого высокого уровня. Репозиторий содержит одну или несколько ветвей.
  • Ветвь — это единица хранения с текущими файлами и папками, которые формируют содержимое проекта. Дополнительные сведения о ветвях см. в разделе Branch этой статьи.

Участники взаимодействуют с 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, где хранится основной репозиторий для любого проекта документации. Копии, создаваемые участниками для собственного использования, распространяются на нескольких компьютерах. В итоге они согласовываются в основном репозитории GitHub проекта.

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

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

Подкаталог статей

Основной каталог articles обычно находится в корне репозитория. Каталог 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.
  • Общие инструкции по использованию расширений технической документации Майкрософт, которые можно применять для специальных элементов управления, таких как кнопки и селекторы.

Источник

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

Запросы на включение внесенных изменений

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

Pr также служит механизмом для предоставления участник обратной связи с процессами проверки Microsoft Learn и рецензентом pr для устранения проблем или вопросов перед объединением изменений в ветвь по умолчанию.

Удаленно

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

Восходящие

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

Подробнее

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

Ресурсы управления версиями Git

Ресурсы по GitHub

Вопросы и ответы

Что такое Git?

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

Почему используйте Git?

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

Как работает Git?

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

Что такое ветви в Git?

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

Что такое фиксация в Git?

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

Что такое GitHub?

GitHub — это веб-сайт, на котором можно хранить проекты Git. Это как большой концентратор для совместного использования и совместной работы над кодом с другими пользователями. Это также помогает следить за тем, кто изменил то, что.

Как GitHub отличается от Git?

Git — это средство отслеживания изменений, а GitHub — это место для хранения проектов и совместной работы. GitHub использует Git для выполнения своей магии.

Является ли GitHub бесплатным?

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

Что такое запросы на вытягивание в GitHub?

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

Насколько безопасно GitHub?

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