Стековые pull request: как разбить большой PR на цепочку

Проблема больших pull request

Вы когда-нибудь открывали PR с 47 изменёнными файлами и диффом настолько длинным, что GitHub просто показывает «Load Diff» семнадцать раз? Если да, эта статья для вас. GitHub тихо выпустил, возможно, крупнейшее обновление pull request за последние годы, и оно направлено именно на эту проблему. Давайте поговорим о стековых pull request.

Проблема в одном предложении

Большие PR — это место, где хорошие ревью умирают. Никто внимательно не читает дифф из 2000 строк. Некоторые прибегают к AI-инструментам для ревью кода, например LiveReview, и это помогает, но даже лучший рецензент (человек или модель) справляется лучше с небольшим сфокусированным диффом, чем с стеной из 2000 строк. Меньше входных данных — лучше ревью. Это верно независимо от того, кто проверяет.

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

Что такое стек на самом деле

Правило простое. Нужно два или более PR в одном репозитории, где:

• Нижний PR направлен в вашу основную ветку (обычно main)
• Каждый следующий PR направлен в PR ниже, а не в main

Вот и всё. Весь трюк. Фундаментальные вещи (схемы, общие типы) идут внизу. То, что от них зависит (API-маршруты, UI), идёт выше по цепочке.

И вот что меня удивило: если вы делаете это вручную с помощью обычного git, открывая PR #11 против ветки PR #10 вместо main, GitHub теперь автоматически распознаёт это как стек. Никаких специальных инструментов не требуется. Он просто замечает, что базовые ветки образуют цепочку, и показывает баннер. Стекинг — это вообще не концепция git, это чисто концепция интерфейса GitHub, наложенная поверх веток, которые вы уже создавали.

Давайте создадим стек

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

Сначала я попробовал использовать CLI-расширение:

$ gh stack --help
unknown command "stack" for "gh"

Да, оказывается, gh stack требует CLI-расширение или более новую версию gh, чем та, что в моём $PATH, а у меня из Ubuntu apt-репозитория, который ещё не знает об этой функции. Софт, что поделать.

Поэтому я сделал это «по-старинке», как упоминается в документации: обычные git-ветки, связанные база с базой, без расширений. С точки зрения git, вы получаете ровно то, что git всегда даёт: три ветки, лежащие друг на друге, как уставшие пассажиры в поезде. Пока ничего особенного. Это просто ветки.

Магия происходит, когда вы пушите их и открываете PR с правильными базами:

$ git push -u origin stack/01-setup-database stack/02-api-endpoints stack/03-setup-frontend

$ gh pr create --base master --head stack/01-setup-database \
    --title "demo: setup database layer"
https://github.com/lovestaco/peektea/pull/10

$ gh pr create --base stack/01-setup-database --head stack/02-api-endpoints \
    --title "demo: add api endpoints"
https://github.com/lovestaco/peektea/pull/11

$ gh pr create --base stack/02-api-endpoints --head stack/03-setup-frontend \
    --title "demo: setup frontend"
https://github.com/lovestaco/peektea/pull/12

Обратите внимание, что --base для PR #11 — это stack/01-setup-database, а не master. Этот единственный флаг — весь секретный соус.

И GitHub действительно замечает

Это меня зацепило. Я ожидал, что придётся вручную включать какую-то настройку. Вместо этого, как только я открыл верхний PR цепочки, GitHub просто показал баннер: «Этот pull request можно сложить в стек с другими pull request», с кнопкой «Preview stack» прямо здесь.

Нажатие на неё открывает небольшой предпросмотр, который проходит всю цепочку от верхнего PR до main, правильно упорядоченную, правильно связанную, без какой-либо настройки с моей стороны, кроме открытия PR с правильными базовыми ветками. Нажмите «Create stack», и каждый PR в списке получит маленький значок прогресса: 1/3, 2/3, 3/3 — прямо в списке pull request, так что вы сразу видите, насколько глубоко данный PR находится в стеке, не открывая ни одного.

Согласно документации GitHub по стековым pull request, когда вы довольны всей цепочкой, есть действие «merge stack», которое проходит вниз и объединяет все PR по порядку за один раз, без ручного ребейза между каждым слиянием. Я не нажимал эту кнопку в своём демо-репозитории (закрыть четыре вкладки браузера — достаточно хаоса для одной статьи), но документация и интерфейс указывают на то, что это одна кнопка для того, что раньше было N последовательных слияний плюс N ребейзов.

Подождите, разве у меня уже не было этого?

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

Что нового — GitHub теперь понимает отношения, отслеживает их как объект первого класса (мой стек получил собственный ID, как только я нажал «Create stack»), показывает прогресс в общем списке и даёт одно действие слияния вместо ручного танца «merge-then-rebase-then-merge» для каждого уровня.

Так что нет, сам git не получил новый примитив для стековых PR. Интерфейс GitHub — да. Если вы клонируете репозиторий и посмотрите на ветки, они ничем не отличаются от любой другой фиче-ветки. «Стек» существует только как метаданные, которые GitHub хранит на своей стороне.

Почему мне это действительно важно (подсказка: дело в ботах)

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

Стековые PR дают агентам третий вариант: строить функцию так, как это сделал бы внимательный человек, — проверяемыми слоями, и пусть сама цепочка зависимостей сообщает порядок. Сначала схема, потом API, которому нужна схема, потом UI, которому нужен API. Вы ревьюите так же, как агент это строил. Больше не нужно выбирать между «одним неревьюябельным PR из 3000 строк» и «двенадцатью PR без видимой связи друг с другом». Стек — это журнал изменений того, как агент на самом деле думал над проблемой.

Стоит ли вам это использовать

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

Если ваша команда сейчас придерживается подхода «один PR на фичу, независимо от размера», стековые PR — хороший способ начать, потому что вы продолжаете работать как раньше (ответвляясь от предыдущей ветки), а GitHub берёт на себя учёт, который вы раньше делали в голове.

Эта функция всё ещё помечена как новая в документации GitHub, так что ожидайте шероховатостей (мой gh CLI даже не знал о такой команде), но веб-интерфейс сработал ровно так, как заявлено, с первой попытки: без настройки, без флага включения, просто откройте PR с правильными базовыми ветками и смотрите, как GitHub соединяет точки.

Практический вывод

Попробуйте стековые PR уже сегодня. Возьмите свою текущую фичу, разбейте её на 2-3 логических слоя (например, схема БД, API, UI) и создайте цепочку PR, направляя каждый следующий в предыдущий. Посмотрите, как GitHub автоматически распознаёт стек и показывает прогресс. Это бесплатно, не требует дополнительных инструментов и может радикально улучшить качество код-ревью в вашей команде.