Руководство разработчика по Backport Builder

Краткий обзор

Backport Builder — проект для инженерии выпусков. Рассматривайте исходные репозитории как входные данные, сгенерированные деревья — как выходные, а пользовательские правила Rector — как протестированную логику сборки.

Используйте это руководство, когда сопровождаете правила понижения, метаданные сгенерированных пакетов, проверки для целевой среды выполнения или автоматизацию выпуска для nextpdf/backport-builder.

Архитектурная граница

Уровень	Владелец	Ответственность	Не размещайте здесь
Исходные репозитории	Репозитории продукта	Канонический исходный код PHP и тесты.	Сгенерированные изменения для понижения.
Скрипты сборки	`nextpdf/backport-builder`	Слияние исходного кода, выполнение преобразований, запись метаданных и проверка вывода.	Прикладная логика времени выполнения.
Конфигурация Rector	`nextpdf/backport-builder`	Политика понижения для конкретной цели.	Предположения для нескольких целей без тестов.
Пользовательские правила Rector	`nextpdf/backport-builder`	Преобразования синтаксиса для конкретного проекта.	Широкие непроверенные переписывания.
Сгенерированные пакеты	Вывод сборки	Устанавливаемые артефакты для более старых сред выполнения.	Ручные правки в источнике истины.

Жизненный цикл сборки

Этап	Поведение	Действие разработчика
Извлечение исходного кода	Рабочий процесс выпуска извлекает исходные репозитории для целевого тега.	Поддерживайте согласованность ссылок на исходный код между пакетами.
Проверка контракта	`ValidateBuildContract::run()` проверяет предположения сборки.	Контракт, который не прошёл проверку, должен блокировать выпуск.
Слияние	`MergeSources::run()` собирает дерево целевого пакета.	Проверьте область целевого пакета перед запуском Rector.
Преобразование	Конфигурации Rector и пользовательские правила понижают синтаксис.	Добавляйте тесты на фикстурах для каждого изменения правила.
Корректировка Composer	`AdjustComposer` записывает метаданные сгенерированного пакета и карты замены.	Проверяйте имена пакетов, версии, лицензии и ограничения.
Проверка во время выполнения	Сгенерированный вывод проходит проверку синтаксиса и тестируется на целевых версиях PHP.	Сбой в целевой среде выполнения должен блокировать выпуск.
Выпуск	Архивы прикрепляются к выпуску.	Не правьте сгенерированный вывод как источник истины.

Рабочая задача	Источник истины	Политика сгенерированного вывода
Использование возможностей PHP	Основной исходный репозиторий.	Правила backport адаптируют эту возможность.
Ограничения зависимостей	Метаданные исходного `composer.json` и скрипт корректировки.	Сгенерированный `composer.json` должен быть воспроизводимым.
Понижение синтаксиса	Конфигурация Rector и пользовательские правила.	Сгенерированный исходный код не следует править вручную.
Поддержка среды выполнения	Целевая ветка и матрица CI.	Сборка должна проходить на целевой версии PHP.
Заметки о выпуске	Документация и автоматизация выпуска.	Сгенерированные артефакты должны ссылаться на исходный выпуск.

Шаблон пользовательского правила Rector

Каждое пользовательское правило должно решать узкую задачу, иметь метаданные и покрытие фикстурами.

Метод правила	Назначение	Требование к качеству
`getRuleDefinition()`	Документирует преобразование для инструментов Rector.	Включите пример before/after, соответствующий фактическому понижению.
`getNodeTypes()`	Ограничивает узлы AST, проверяемые правилом.	Сохраняйте список узлов как можно меньшим.
`refactor()`	Применяет преобразование или возвращает узел без изменений.	Не меняйте несвязанные узлы; поведение должно оставаться детерминированным.
Тест на фикстуре	Проверяет вывод before/after.	Покройте наименьший допустимый ввод и хотя бы один случай пропуска.

<?php

final class ExampleDowngradeRector extends AbstractRector
{
    public function getNodeTypes(): array
    {
        return [SomeNode::class];
    }

    public function refactor(Node $node): ?Node
    {
        if (!$node instanceof SomeNode) {
            return null;
        }

        return $this->rewriteNode($node);
    }
}

Шаблон команды сборки

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

composer build:dry
php scripts/build.php --version=2.0.0 --target=php81 --dry-run
php scripts/build.php --version=2.0.0 --target=php74 --no-pro

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

Точки расширения

Точка расширения	Используется для	Ограничение
Файлы конфигурации Rector	Политика понижения для конкретной цели.	Держите линии PHP 8.1 и PHP 7.4 отдельно друг от друга.
Пользовательские правила Rector	Преобразования синтаксиса для конкретного проекта.	Должны иметь метаданные и тесты на фикстурах.
Скрипт корректировки Composer	Идентичность сгенерированного пакета.	Должен сохранять версионирование, согласованное с SemVer.
Скрипт слияния	Выбор и формирование входных данных исходного пакета.	Должен записывать в журнал корни исходного кода и корни вывода.
Рабочий процесс сборки	Оркестрация выпуска.	Должен проверять сгенерированный вывод в целевой среде выполнения.

Рабочий процесс разработки

Воспроизведите неподдерживаемый синтаксис в минимальной фикстуре.
Добавьте или обновите пользовательское правило Rector.
Добавьте фикстуры before/after для правила.
Запустите сухую сборку.
Проверьте сгенерированный вывод в целевой среде выполнения PHP.
При необходимости примените то же логическое изменение к каждой долгоживущей целевой ветке.
Поддерживайте воспроизводимость артефактов выпуска из тегов исходного кода и скриптов сборки.

Обработка сбоев

Сбой	Где обрабатывать	Рекомендуемая реакция
Отсутствует исходный репозиторий	Этап проверки контракта или слияния.	Остановите сборку и исправьте данные для извлечения.
Сбой разбора Rector	Этап преобразования.	Сведите проблему к фикстуре и обновите правило или конфигурацию.
Несоответствие в сгенерированном файле `composer.json`	Этап корректировки Composer.	Исправьте скрипт генерации, а не сгенерированные метаданные.
Сбой целевого синтаксиса	Проверка во время выполнения.	Блокируйте выпуск, пока преобразование не будет исправлено.
Источник Pro недоступен	Конфигурация сборки.	Собирайте публичный артефакт только если именно это является предполагаемой целью.

Безопасные значения по умолчанию

Аспект	По умолчанию	Когда переопределять
Сгенерированный вывод	Артефакт только для чтения.	Никогда не делайте его источником истины.
Модель ветвления	Раздельные долгоживущие целевые ветки.	Синхронизируйте изменения через независимые запросы на слияние.
Хост сборки	Современная версия PHP.	Готовность к выпуску по-прежнему определяет проверка целевой среды выполнения.
Пользовательские правила	Небольшие и подкреплённые фикстурами.	Избегайте широких преобразований без явных примеров before/after.
Линия PHP 7.4	Только Core, если иное не поддерживается явно.	Не включайте вывод Pro без проверки целевой среды выполнения.

Контрольный список тестирования

Тесты метаданных правил Rector создают экземпляры каждого пользовательского правила.
Тесты на фикстурах покрывают код before/after для каждого преобразования.
Сухая сборка выполняется перед заданиями выпуска.
Проверки синтаксиса целевой среды выполнения и тесты пакетов выполняются на сгенерированном выводе.
Тесты метаданных Composer проверяют имя пакета, версию, ограничения, карту замены и лицензию.
Журналы сборки включают пути к исходному коду, целевой путь, целевую среду выполнения, состояние сухого прогона и статус включения Pro.