Подготовка Merge Request

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

В этом уроке подготовим локальный материал для будущего запроса в GitLab. Сценарий lesson-14 архива содержит исходный каталог, ожидаемый файл и отдельный черновик описания. Никакой запрос в действительном GitLab не создаётся, история не передаётся, команды и проверки не выполнялись.

Одно изменение поведения

Исходный каталог содержит заголовок, две ссылки и рекомендации. Читателю ещё не объясняется порядок прохождения материалов. Добавим перед списком один абзац: «В каждом курсе переходите от первого урока к следующему.» Существующие названия и URL остаются прежними. Это узкая редакционная задача, которую можно оценить отдельно от расширения всего каталога.

Создайте в подготовленной лаборатории ветку feature/course-order. Измените только content/courses.md, прочитайте различие и сохраните законченный абзац отдельным коммитом. Учебные команды выглядят так:

git switch -c feature/course-order
git diff -- content/courses.md
git add content/courses.md
git commit -m "Объяснить порядок прохождения курса"

Перед записью ожидается только добавление объяснения. Если вместе с ним появились изменения оформления, новые URL или результат сборки, остановитесь и уточните состав задачи. Чем яснее её границы, тем легче рецензенту понять, какие последствия требуется оценить.

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

Различие относительно общей основы

В нашей модели main после создания ветки не меняется. Сравнение источника и назначения поэтому показывает одну запись и один абзац. Тем не менее прочитаем явно тот вариант, который предназначен для будущего обсуждения:

git log --oneline main..feature/course-order
git diff main...feature/course-order -- content/courses.md

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

Список коммитов и итоговое различие следует читать вместе. Например, несколько записей могут последовательно добавлять, редактировать и сокращать один абзац. Рецензенту важно конечное поведение, но история помогает объяснить спорное решение. Не нужно заставлять его угадывать цель по случайным сообщениям «правка» и «ещё правка».

Если основная ветка изменилась, сначала получите актуальные сведения и проверьте согласованность будущего объединения. Не добавляйте в описание утверждение «конфликтов нет» только потому, что ваша рабочая папка чистая. Чистое дерево описывает незаписанные локальные правки, а совместимость веток относится к другому состоянию.

Описание для рецензента

Подготовим текст, который можно перенести в будущий Merge Request. Он хранится в review/request.md сценария вне учебного рабочего дерева. Это предотвращает случайное включение служебного черновика в изменение самой страницы.

Каталог перечисляет курсы, но не объясняет порядок чтения уроков.
Перед списком добавлено пояснение о переходе от первого урока к следующему.
Названия курсов и существующие URL сохранены.

Подготовлено различие одного Markdown-файла.
Пример, сборка и проверки ещё не выполнялись.
Запрос в GitLab и публикация не создавались.

Для ревью: проверить положение абзаца и сохранение двух исходных ссылок.

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

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

Также стоит указать вопрос, по которому нужна оценка: порядок абзаца и сохранение ссылок. Это помогает рецензенту начать с предмета изменения. Общая просьба «посмотрите всё» может породить обсуждение несвязанных деталей, особенно когда небольшой документ расположен внутри большой библиотеки.

Описание полезно перечитать после последней правки, а не считать неизменным с начала задачи. Если автор убрал первоначальный абзац и вместо него добавил подсказку рядом с каждым курсом, цель и итоговое различие уже расходятся с черновиком. Рецензент получит неверный контекст даже при аккуратных коммитах. Для нашей модели изменение осталось одним пояснением, поэтому текст можно проверить почти дословно: проблема порядка чтения раскрыта, абзац появился перед списком, две ссылки сохранены. Такая связь делает описание устойчивым к сокращению: каждое предложение сообщает существенное свойство. Если появилась новая независимая идея, например добавить третий курс, лучше вынести её в следующую задачу. Иначе небольшой запрос неожиданно потребует проверки новых маршрутов и содержания, которые не были частью исходного результата. Разделение задачи помогает и будущему возврату: отменить пояснение можно, не затронув независимое пополнение библиотеки.

Источник и назначение запроса

Когда команда позднее разрешит внешнее действие, в GitLab потребуется выбрать исходную ветку feature/course-order и целевую main нужного проекта. Проверяйте обе стороны до создания запроса. Одинаковое название ветки в другом проекте ещё не делает её частью нашей задачи.

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

Черновик запроса полезен для раннего обсуждения, но не заменяет критерии готовности. Если абзац уже согласован, однако локальный показ ещё не просмотрен, это два разных состояния. Аналогично одобрение рецензента не означает, что сайт задеплоен: объединение исходников и выпуск на хостинг должны иметь отдельное назначение.

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

В результате у нас подготовлена одна ветка с понятным изменением, ожидаемый Markdown и описание, которое раскрывает проблему, результат и ограничения. Запрос остаётся будущим внешним действием. В следующем уроке посмотрим на такую работу глазами рецензента и сформулируем конкретное замечание.