Guide développeur du Backport Builder

En bref

Le Backport Builder est un projet de release engineering. Traite les dépôts source comme une entrée, les arborescences générées comme une sortie et les règles Rector personnalisées comme une logique de build testée.

Suis ce guide lorsque tu maintiens les règles de downgrade, les métadonnées de package générées, les vérifications du runtime cible ou l’automatisation de publication autour de nextpdf/backport-builder.

Frontière d’architecture

Couche	Propriétaire	Responsabilité	À ne pas placer ici
Dépôts source	Dépôts produit	Source PHP et tests de référence.	Modifications de downgrade générées.
Scripts de build	`nextpdf/backport-builder`	Fusionner la source, exécuter les transformations, écrire les métadonnées, valider la sortie.	Logique applicative d’exécution.
Configuration Rector	`nextpdf/backport-builder`	Politique de downgrade propre à la cible.	Hypothèses entre cibles sans tests.
Règles Rector personnalisées	`nextpdf/backport-builder`	Transformations de syntaxe spécifiques au projet.	Réécritures larges et non testées.
Packages générés	Sortie de build	Artefacts installables pour les runtimes plus anciens.	Correctifs manuels de la source de référence.

Cycle de vie du build

Étape	Comportement	Action du développeur
Récupération de la source	Le workflow de publication récupère les dépôts source au tag cible.	Garde les références source alignées entre les packages.
Validation du contrat	`ValidateBuildContract::run()` vérifie les hypothèses du build.	Considère tout échec de contrat comme bloquant pour la publication.
Fusion	`MergeSources::run()` assemble l’arborescence du package cible.	Vérifie le périmètre de la cible avant d’exécuter Rector.
Transformation	Les configurations Rector et les règles personnalisées rétrogradent la syntaxe.	Ajoute des tests de fixture pour chaque modification de règle.
Ajustement de Composer	`AdjustComposer` écrit les métadonnées de package générées et les replace maps.	Valide les noms de package, la version, la licence et les contraintes.
Validation du runtime	La sortie générée fait l’objet d’une vérification de syntaxe et de tests sur les versions PHP cibles.	Considère tout échec sur le runtime cible comme bloquant pour la publication.
Publication	Les archives sont attachées à une release.	Ne corrige pas la sortie générée comme s’il s’agissait de la source de référence.

Workflow de dépôt recommandé

Élément de travail	Source de référence	Politique de sortie générée
Usage des fonctionnalités PHP	Dépôt source principal.	Les règles de backport adaptent la fonctionnalité.
Contraintes de dépendances	Métadonnées source `composer.json` et script d’ajustement.	Le `composer.json` généré doit être reproductible.
Downgrade de syntaxe	Configuration Rector et règles personnalisées.	La source générée ne doit pas être modifiée manuellement.
Support du runtime	Branche cible et matrice CI.	Le build doit réussir sur le PHP cible.
Notes de version	Documentation et automatisation de publication.	Les artefacts générés doivent pointer vers la release source.

Modèle de règle Rector personnalisée

Chaque règle personnalisée doit avoir un objectif précis, des métadonnées et une couverture par fixture.

Méthode de la règle	Objectif	Exigence de qualité
`getRuleDefinition()`	Documente la transformation pour l’outillage Rector.	Inclut un exemple before/after qui correspond au downgrade réel.
`getNodeTypes()`	Limite les nœuds AST inspectés par la règle.	Garde la liste de nœuds aussi petite que possible.
`refactor()`	Applique la transformation ou renvoie le nœud inchangé.	Laisse les nœuds non concernés inchangés, avec un résultat déterministe.
Test de fixture	Vérifie la sortie before/after.	Couvre la plus petite entrée valide et au moins un cas ignoré.

<?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);
    }
}

Modèle de commande de build

Utilise des dry runs pendant le développement et la validation des release candidates. Ne produis la sortie réelle que lorsque les références source et la branche cible sont connues.

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

La validation du package généré doit s’exécuter sur le runtime cible, pas uniquement sur l’hôte de build moderne.

Points d’extension

Point d’extension	À utiliser pour	Contrainte
Fichiers de configuration Rector	Politique de downgrade propre à la cible.	Garde les voies PHP 8.1 et PHP 7.4 séparées.
Règles Rector personnalisées	Transformations de syntaxe spécifiques au projet.	Doivent avoir des métadonnées et des tests de fixture.
Script d’ajustement de Composer	Identité du package généré.	Doit préserver le versionnage aligné sur SemVer.
Script de fusion	Sélection et préparation de l’entrée du package source.	Doit journaliser les racines source et les racines de sortie.
Workflow de build	Orchestration de publication.	Doit valider la sortie générée sur le runtime cible.

Workflow de développement

Reproduis la syntaxe non prise en charge dans une fixture minimale.
Ajoute ou mets à jour une règle Rector personnalisée.
Ajoute des fixtures before/after pour la règle.
Lance le build à blanc.
Valide la sortie générée sur le runtime PHP cible.
Applique la même modification logique à chaque branche cible permanente lorsque c’est nécessaire.
Garde les artefacts de publication reproductibles à partir des tags source et des scripts de build.

Gestion des échecs

Échec	Où il doit être traité	Réponse recommandée
Dépôt source manquant	Étape de validation du contrat ou de fusion.	Arrête le build et corrige les entrées du checkout.
Échec d’analyse Rector	Étape de transformation.	Réduis à une fixture et mets à jour la règle ou la configuration.
Incohérence du `composer.json` généré	Étape d’ajustement de Composer.	Corrige le script de génération, pas les métadonnées générées.
Échec de syntaxe sur la cible	Validation du runtime.	Bloque la publication jusqu’à ce que la transformation soit corrigée.
Source Pro indisponible	Configuration du build.	Ne construis l’artefact public que lorsque c’est la cible visée.

Valeurs par défaut sûres

Préoccupation	Par défaut	Quand y déroger
Sortie générée	Artefact en lecture seule.	N’en fais jamais la source de référence.
Modèle de branches	Branches cibles permanentes séparées.	Garde les modifications synchronisées via des pull requests indépendantes.
Hôte de build	PHP moderne.	La validation sur le runtime cible reste le critère d’aptitude à la publication.
Règles personnalisées	Petites et adossées à des fixtures.	Évite les transformations larges sans exemples before/after explicites.
Voie PHP 7.4	Core uniquement, sauf prise en charge explicite.	N’inclus pas la sortie Pro sans validation sur le runtime cible.

Liste de vérification des tests

Les tests de métadonnées de règle Rector instancient chaque règle personnalisée.
Les tests de fixture couvrent le code avant et après pour chaque transformation.
Le build à blanc s’exécute avant les jobs de publication.
Les vérifications de syntaxe sur le runtime cible et les tests de package s’exécutent sur la sortie générée.
Les tests de métadonnées Composer vérifient le nom du package, la version, les contraintes, la replace map et la licence.
Les logs de build incluent les chemins source, le chemin cible, le runtime cible, l’état dry-run et l’état d’inclusion de Pro.