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

  • Статья
  • Чтение занимает 5 мин

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

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

Быстрый старт в GitLab | МИЭМ Wiki

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

GitLab

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

Перед началом работы с GitLab установите себе на устройство приложение Git по ссылке.

Найти подробную инструкцию по установке Git можно здесь.

Авторизуйтесь в сервисе GitLab через корпоративную почту @miem.hse.ru.

Затем выберите в верхней панели раздел «Groups». Щелкните на «Your Groups». На этой странице должна находиться группа с номером и названием вашего проекта. Нажмите на нее, чтобы открыть.

Если после авторизации вы не видите группу своего проекта, то обратитесь в Техподдержку.

После авторизации нужно установить пароль для вашего аккаунта в GitLab.

  1. Нажмите на вашу иконку в правом верхнем углу и перейдите в раздел «Настройки» (settings).

  2. Затем перейдите во вкладку «Пароль» (password).

  1. Укажите ваш новый пароль и сохраните его.

Репозиторий (хранилище) — место, где хранятся и поддерживаются данные. Чаще всего данные в репозитории хранятся в виде файлов.

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

Узнать более подробную информацию можно перейдя по ссылке: что такое репозиторий?

Шаг 1. Зайдите в свой аккаунт на GitLab и нажмите на иконку «Groups» в верхней панели.

Шаг 2. Затем перейдите во вкладку «Your group».

Шаг 3. Выберите команду с названием вашего учебного проекта.

Если вы не видите в разделе «Your group» команду вашего проекта, то обратитесь в Техподдержку.

Шаг 4. Вы перешли на страницу своей команды. Теперь нужно создать репозиторий. Для этого нажмите на кнопку «New project».

Если у вас уже есть нужный вам репозиторий, то перейдите к шагу 6.

Шаг 5. Напишите название вашего репозитория и добавьте нужные данные. Готово!

Рекомендуем установить галочку напротив «Инициализировать репозиторий файлом README» — в репозитории появится документ «README. md», в котором можно описывать файлы, содержащиеся в этом репозитории.

Если вы хотите залить сюда файлы из уже существующего репозитория, то можеть не создавать новый «README. md».

Шаг 6.

Перенос существующего репозитория Если у вас уже есть репозиторий на MIEM GitLab, то его легко можно перенести:
  1. Для этого зайдите на страницу нужного вам проекта. Далее перейдите в настройки.

  1. Опуститесь до раздела «Advanced» и разверните его с помощью кнопки «
    Expand    «.

  1. Найдите внутри блок «Transfer project» и с помощью селектора выберите новое расположение.

Переместить проект может человек только с ролью «Maintainer»(подробнее в разделе участники и роли)

Перенос существующего репозитория с другой платформы

Если проект был создан на другой платформе (Github, Bitbucket и т.д.), то при создании нового репозитория откройте вверху вкладку «Import project» вместо «Blank project«, а затем выберите » Repo by URL«.

Нужно обязательно выбрать «Repo by URL«, в остальных случаях импорт не всегда проходит успешно

Подробнее о миграции проектов.

При этом вся информация по коммитам будет перенесена. Однако, чтобы она корректно отображалась и учитывалась в статистике, необходимо, чтобы коммиты были сделаны с почты @miem.hse.ru. Если коммиты были сделаны с другой почты, то необходимо добавить ее адрес в личном кабинете в Git.miem.hse.ru (подробнее в блоке «Коммит»)

Откройте нужный репозиторий и нажмите на кнопку «Clone». Скопируйте ссылку.

Далее вам нужно перейти в консоль.

Как это сделать?

  • Windows
  1. Нажмите на значок поиска на Панели задач или кнопку Пуск.
  2. Далее нажимите «Выполнить».

  1. В строке поиска напечатайте «cmd».

  1. В результате вы увидите окно консоли.

Не на всех видах Windows консоль открывается так, как указано выше. НО на всех можно нажать Win+R и ввести cmd.

  • Mac
  1. В строке поиска Spotlight введите слово «Терминал» и нажмите Enter.
  2. В результате вы увидите окно терминала.
  • Linux
    Для открытия консоли (терминала) нажмите сочитание следующих клавиш: Alt+Ctrl+F1.

Для получения копии существующего Git-репозитория необходимо ввести в терминале команду git clone.

То есть мы просим Git создать копию репозитория, который находится по ссылке (<ссылка на репозиторий>), и можем указать путь к директории, в которую Git скопирует репозиторий (<директория>). Если его не указать, директория создастся в каталоге, где вы находитесь, когда выполняете команду и будет называться так же, как и сам репозиторий.

Клонирование репозитория осуществляется командой:
git clone <ссылка на репозиторий> <путь к директории>

После вы должны ввести имя пользователя и пароль от своей учетной записи в GitLab.

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

Вы можете в любой момент перейти к папке с вашим репозиторием с помощью команды:
cd путь/к/директории

Следующая команда показывает, что файл «README.md» скачался и лежит в нашей папке:
dir (ls в Unix)

клонирование репозитория прошло успешно

Первое, что вам следует сделать после установки Git — указать ваше имя и адрес электронной почты. Каждый коммит в Git, сделанный вами, будет содержать эти данные. Это информация о разработчике, который вносит изменения.
Используем следующие команды:
git config --global user.name "Иван Иванов"
git config --global user.email [email protected]

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

Если вы хотите проверить используемую конфигурацию, можете использовать команду git config --list, чтобы показать все настройки, которые Git найдёт:

Одной из важнейших команд является git status. Система отслеживает изменения, и с помощью этой команды мы узнаем о состоянии системы. Если выполнить эту команду сразу после клонирования, то можно увидить что-то вроде этого:

Это означает, что у вас чистый рабочий каталог. Другими словами, в нем нет отслеживаемых измененных файлов. Git также не обнаружил неотслеживаемых файлов, в противном случае они бы были перечислены здесь.

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

GitLab предоставляет простой способ внести небольшие изменения в файлы проекта. Это среда разработки, встроенная в сайт GitLab. Чтобы её запустить, найдите файл, который нужно отредактировать и щелкните по его названию. На открывшейся странице вы увидите содержимое файла и две кнопки: Edit и Web IDE. Первая кнопка откроет файл для простого редактирования, вторая запустит встроенную среду разработки.

Также на сайте предусмотрена возможность создавать новые файлы. Для этого на странице репозитория нажмите на кнопку "+" и выберите "New file". В открывшемся редакторе введите имя файла и нужное содержимое. Не забудьте нажать на кнопку Commit changes по завершении редактирования.

Кроме того, для частых типов файлов предусмотрены отдельные кнопки. Вы найдёте их над списком файлов на странице репозитория. Так вы, например, сможете быстро добавить файл README.md в ваш проект. Просто нажмите на кнопку Add README.

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

Если вы выполните команду git status, то увидите свои неотслеживаемые изменения в файле:

Мы видим, что у нас есть недобавленные изменения.

Для добавления изменений используется команда git add <название файла>. Команда git add . добавляет все изменения в рабочей директории в индекс для последующего коммита.

Коммит — это сохранение, фиксация (в архиве, репозитарии и т.д.) изменений в программном коде.

Команда git commit берёт все данные, добавленные в индекс с помощью git add, и сохраняет их слепок во внутренней базе данных, а затем сдвигает указатель текущей ветки на этот слепок.

Более подробная информация о коммите.

При коммите данных их необходимо комментировать, чтобы в дальнейшем каждое изменение в проекте было с описанием действий. Для этого используется команда
git commit -m "комментарий"

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

Для того чтобы залить изменения в удаленный репозиторий, который находится на git.miem.hse.ru, нужно использовать команду git push.

Рассмотрим пример:
Создадим новый файл «text. txt» в папке «main» и выполним следующие действия:

Шаг 1. Добавим файл в нашу папку main;

Шаг 2. Зафиксируем изменения и узнаем текущее состояние файла;

Шаг 3. Отправим изменения в локальное хранилище (то есть выполним коммит).

С помощью команды git push отправим данные локального репозитория на удаленный репозиторий (Origin — это наш репозиторий).

Заходим в GitLab и видим, что отправка данных прошла успешно.

Если вы добавили файлы в состояние ожидания, но передумали и не хотите добавлять некоторые из них, то нужно использовать команду:
git rm --cached "название файла"

Укажите, какой файл необходимо удалить из ожидания на коммит.

  • Если вы ввели неправильно пароль (на Windows), а во второй раз ваши данные не запрашиваются, то вам нужно сделать следующие действия:
    панель управления -> учетные записи -> диспетчер учетных данных -> удалить данные GitLab
    После чего заново повторить первые шаги с вводом ваших данных.

  • Чтобы на устройствах Linux/Mac каждый раз не запрашивался пароль, нужно использовать следующую команду:
    git config credential.helper store

  1. Основные понятия: Ветки
  2. Основные понятия: Зеркалирование репозитория
  3. Управление командой: Различия прав доступа
  4. Навигация: Уровень видимости проекта

GitHub приостанавливает действие учетных записей российских разработчиков в компаниях, находящихся под санкциями

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

По сообщениям российских СМИ, волна запретов началась 13 апреля и не делала различий между компаниями и физическими лицами.

Например, для учетных записей GitHub компаний «Сбербанк Технологии», «Лаборатория искусственного интеллекта Сбербанка» и «Лаборатория Альфа-Банка» изначально были отключены репозитории кода, и теперь они удалены с платформы.

Заблокированный репозиторий или отмеченная компания (habr.com)

Учитывая, что на прошлой неделе эти компании были подвергнуты санкциям Министерства финансов США, а Microsoft владеет американской компанией GitHub, действия не являются неожиданными.

Тем не менее, приостановка действия личных учетных записей десятков лиц, на которых не размещается контент, связанный с какими-либо санкционированными организациями, вызывает удивление.

Пользователь GitHub жалуется на необоснованную приостановку учетной записи

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

Habr.com сообщает, что некоторые российские разработчики связались с GitHub по поводу приостановки и получили электронное письмо под названием «GitHub и торговый контроль», в котором объяснялось, что их учетная запись была отключена из-за санкций США.

Письмо о приостановке
Источник: Habr

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

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

Разработчик опубликовал в Твиттере сообщение о том, что он может отменить блокировку после заполнения формы и что это связано с санкциями его предыдущего работодателя.

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

«Параллельно с нашими усилиями по обеспечению доступности GitHub для разработчиков во всех странах мы продолжаем обеспечивать доступность бесплатных сервисов с открытым исходным кодом для всех, включая разработчиков в России», — говорится в сообщении платформы, опубликованном в марте прошлого года. .

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

Bleeping Computer обратился к GitHub с просьбой прокомментировать сообщение о волне приостановки, и представитель платформы ответил следующим образом:

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

В то же время GitHub стремится стать глобальной платформой для совместной работы разработчиков, где бы они ни находились. Мы тщательно изучаем правительственные санкции, чтобы убедиться, что пользователи и клиенты не пострадали сверх того, что требуется по закону. — Гитхаб

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

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

Перевести GitLab на ваш язык

  • Экстернализация строк
  • Перевод строк
  • Вычитка
  • Выпуск

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

Участие в переводах всегда необходимо. Многие строки еще не доступны для перевода потому что они не экстернализированы. Помощь в экстернализации строк приносит пользу всем языкам. Некоторый переводы неполные или непоследовательные. Перевод строк помогает завершить и улучшить каждый язык.

Есть много способов внести свой вклад в перевод GitLab.

Экстернализация строк

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

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

См. Экстернализация для GitLab.

Перевод строк

Процесс перевода управляется на https://translate.gitlab.com с помощью Краудина. Вы должны создать учетную запись Crowdin, прежде чем сможете отправлять переводы. После входа выберите язык, на который вы хотите сделать перевод.

Голосование за переводы также ценно, поскольку помогает подтвердить хорошие переводы и отметить неточные те.

См. Руководство по переводу.

Вычитка

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

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

Выпуск

Переводы обычно включаются в следующий основной или дополнительный выпуск.

См. Объединение переводов от Crowdin.

Помощь и обратная связь

Документы

Редактировать эту страницу чтобы исправить ошибку или добавить улучшение в мерж-реквест.
Создать задачу чтобы предложить улучшение этой страницы.
Показать и опубликовать комментарии чтобы просмотреть и оставить отзыв об этой странице.

No related posts.