Guia do desenvolvedor para o Backport Builder

Visão geral

O Backport Builder é um projeto de engenharia de release. Trate os repositórios de origem como entradas, as árvores geradas como saídas e as regras personalizadas do Rector como lógica de build testada.

Use este guia quando você mantiver regras de downgrade, metadados de pacotes gerados, verificações de runtime de destino ou automação de release para nextpdf/backport-builder.

Limite da arquitetura

Camada	Pertence a	Responsabilidade	Não coloque aqui
Repositórios de origem	Repositórios do produto	Código-fonte PHP e testes autoritativos.	Edições de downgrade geradas.
Scripts de build	`nextpdf/backport-builder`	Mescla a origem, executa transformações, grava metadados e valida a saída.	Lógica de aplicação em runtime.
Configuração do Rector	`nextpdf/backport-builder`	Política de downgrade específica para o destino.	Suposições entre destinos sem testes.
Regras personalizadas do Rector	`nextpdf/backport-builder`	Transformações de sintaxe específicas do projeto.	Reescritas amplas sem testes.
Pacotes gerados	Saída do build	Artefatos instaláveis para runtimes mais antigos.	Patches manuais na fonte de verdade.

Ciclo de vida do build

Etapa	Comportamento	Ação do desenvolvedor
Checkout da origem	O workflow de release faz checkout dos repositórios de origem na tag de destino.	Mantenha as referências de origem alinhadas entre os pacotes.
Validação do contrato	`ValidateBuildContract::run()` verifica as suposições do build.	Trate um contrato com falha como bloqueador de release.
Mesclagem	`MergeSources::run()` monta a árvore do pacote de destino.	Verifique o escopo de destino antes de executar o Rector.
Transformação	As configurações do Rector e as regras personalizadas fazem o downgrade da sintaxe.	Adicione testes de fixture para cada alteração de regra.
Ajuste do Composer	`AdjustComposer` grava os metadados do pacote gerado e os mapas de replace.	Valide nomes, versões, licenças e restrições dos pacotes.
Validação em runtime	A saída gerada passa por verificação de sintaxe e é testada nas versões de PHP de destino.	Trate uma falha no runtime de destino como bloqueador de release.
Release	Os arquivos compactados são anexados a uma release.	Não aplique patches na saída gerada como fonte de verdade.

Workflow de repositório recomendado

Item de trabalho	Fonte de verdade	Política de saída gerada
Uso de recursos do PHP	Repositório de origem principal.	As regras de backport adaptam o recurso.
Restrições de dependências	Metadados do `composer.json` de origem mais o script de ajuste.	O `composer.json` gerado deve ser reproduzível.
Downgrade de sintaxe	Configuração do Rector e regras personalizadas.	O código-fonte gerado não deve ser editado manualmente.
Suporte de runtime	Branch de destino e matriz de CI.	O build deve passar no PHP de destino.
Notas de release	Documentação e automação de release.	Os artefatos gerados devem ter um link de volta para a release de origem.

Padrão de regra personalizada do Rector

Cada regra personalizada deve ter um propósito restrito, metadados e cobertura por fixture.

Método da regra	Propósito	Requisito de qualidade
`getRuleDefinition()`	Documenta a transformação para o tooling do Rector.	Inclua uma amostra before/after que corresponda ao downgrade real.
`getNodeTypes()`	Limita os nós da AST inspecionados pela regra.	Mantenha a lista de nós a menor possível.
`refactor()`	Aplica a transformação ou retorna sem alterações.	Mantenha os nós não relacionados inalterados e determinísticos.
Teste de fixture	Verifica a saída before/after.	Cubra a menor entrada válida e pelo menos um caso de skip.

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

Padrão de comando de build

Use execuções dry-run durante o desenvolvimento e a validação de candidatos a release. Grave a saída real somente quando as referências de origem e o branch de destino forem conhecidos.

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

Execute a validação do pacote gerado no runtime de destino, não apenas no host de build moderno.

Pontos de extensão

Ponto de extensão	Use para	Restrição
Arquivos de configuração do Rector	Política de downgrade específica para o destino.	Mantenha as faixas de PHP 8.1 e PHP 7.4 separadas.
Regras personalizadas do Rector	Transformações de sintaxe específicas do projeto.	Devem ter metadados e testes de fixture.
Script de ajuste do Composer	Identidade do pacote gerado.	Deve preservar o versionamento alinhado ao SemVer.
Script de mesclagem	Selecionar e moldar a entrada do pacote de origem.	Deve registrar em log as raízes de origem e de saída.
Workflow de build	Orquestração de release.	Deve validar a saída gerada no runtime de destino.

Workflow de desenvolvimento

Reproduza a sintaxe não suportada em um fixture mínimo.
Adicione ou atualize uma regra personalizada do Rector.
Adicione fixtures before/after para a regra.
Execute o build dry.
Valide a saída gerada no runtime de PHP de destino.
Aplique a mesma alteração lógica a cada branch de destino permanente quando necessário.
Mantenha os artefatos de release reproduzíveis a partir das tags de origem e dos scripts de build.

Tratamento de falhas

Falha	Onde deve ser tratada	Resposta recomendada
Repositório de origem ausente	Etapa de validação do contrato ou de mesclagem.	Pare o build e corrija as entradas de checkout.
Falha de parse do Rector	Etapa de transformação.	Reduza a um fixture e atualize a regra ou a configuração.
Incompatibilidade do `composer.json` gerado	Etapa de ajuste do Composer.	Corrija o script de geração, não os metadados gerados.
Falha de sintaxe no destino	Validação em runtime.	Bloqueie a release até que a transformação seja corrigida.
Origem Pro indisponível	Configuração do build.	Crie o artefato público somente quando esse for o destino pretendido.

Padrões seguros

Preocupação	Padrão	Quando substituir
Saída gerada	Artefato somente leitura.	Nunca a transforme na fonte de verdade.
Modelo de branches	Branches de destino permanentes e separados.	Mantenha as alterações sincronizadas por meio de pull requests independentes.
Host de build	PHP moderno.	A validação no runtime de destino ainda decide a prontidão da release.
Regras personalizadas	Pequenas e apoiadas por fixtures.	Evite transformações amplas sem exemplos before/after explícitos.
Faixa de PHP 7.4	Apenas Core, a menos que seja explicitamente suportado.	Não inclua a saída Pro sem validação no runtime de destino.

Checklist de testes

Os testes de metadados das regras do Rector instanciam cada regra personalizada.
Os testes de fixture cobrem o código before e after de cada transformação.
O build dry é executado antes dos jobs de release.
As verificações de sintaxe do runtime de destino e os testes de pacote são executados na saída gerada.
Os testes de metadados do Composer asseguram o nome do pacote, a versão, as restrições, o mapa de replace e a licença.
Os logs de build incluem os caminhos de origem, o caminho de destino, o runtime de destino, o estado de dry-run e o estado de inclusão do Pro.