Alterar o monorepositório de uma plataforma distribuída de trabalhos e testá-lo com serviços reais

## Execute comandos a partir da raiz e escolha a verificação pelo tipo de pacote Execute comandos do espaço de trabalho a partir da raiz do repositório por meio do wrapper fixado do gerenciador de pacotes. Compile as dependências necessárias antes de iniciar um aplicativo ou ferramenta de linha de comando e use filtros do espaço de trabalho para limitar o trabalho ao grafo de pacotes afetado. Siga exatamente a política de instalação de dependências do repositório. Se ela exigir a edição das declarações dos pacotes antes da instalação, faça isso em vez de executar um comando de adição que contorne escolhas de versão passíveis de revisão. Escolha a verificação de acordo com a função do pacote: - Aplicativos e pacotes privados usam verificação estática de tipos quando a compilação não comprova a correção. - Pacotes publicados usam a compilação real do pacote para exercitar as exportações e os artefatos gerados. - Alterações importantes, novos arquivos, trabalho de esquema e refatorações amplas recebem verificação local de tipos ou de compilação. - Edições mínimas podem depender de verificações focadas e da integração contínua quando o projeto permitir explicitamente. Não execute uma compilação ampla apenas por ser familiar. Use a verificação que possa realmente falhar para a camada alterada. ## Teste filas e bancos de dados com contêineres de serviços reais, não com mocks Coloque os testes junto ao código-fonte e use o único executor de testes compatível com o repositório. Comece pelo pacote afetado ou por um arquivo de teste e compile antes suas dependências somente quando o espaço de trabalho exigir. Não substitua bancos de dados, filas ou caches por simulações quando o projeto fornecer contêineres de serviço descartáveis. Use auxiliares de teste isolados que ofereçam opções reais de conexão e estado limpo para: - Comportamento de filas e caches. - Transações relacionais e migrações. - Fluxos de trabalho combinados que atravessem limites de armazenamento. Reserve um limite unitário leve para funções puras. Para o comportamento de infraestrutura, prefira um serviço real controlado para manter visíveis a serialização, a temporização, as novas tentativas e a semântica das transações. Execute a formatação e as correções automáticas de lint antes da verificação final de lint somente leitura. Prefira importações estáticas; use carregamento dinâmico apenas em caso de ciclo inevitável, benefício medido da divisão de código ou condição real do ambiente de execução. ## Registre alterações em pacotes publicados e use uma só versão nas dependências compartilhadas Adicione um registro de alteração versionado sempre que um pacote publicado ou uma integração mudar. Use por padrão um lançamento de correção para consertos e pequenas alterações compatíveis, confirme um lançamento secundário com os mantenedores e nunca selecione um lançamento principal sem aprovação explícita. Para comportamentos exclusivos do servidor sem alteração de pacote publicado, use o mecanismo de notas de alteração do servidor em vez de um registro de versão de pacote. Escreva descrições de lançamento para os usuários: - Comece pelo comportamento alterado. - Use uma frase simples sempre que possível. - Omita nomes internos de ferramentas, filas, armazenamento e implantação. - Não descreva a implementação como o benefício. Mantenha as dependências compartilhadas intencionalmente em uma única versão exata em todo o espaço de trabalho quando a identidade dos tipos no ambiente de execução depender disso. Antes de adicionar uma dependência desse tipo, localize a versão já fixada e corresponda a ela exatamente; intervalos ou versões paralelas podem tornar esquemas de um pacote incompatíveis com consumidores de outro. ## Siga o caminho da requisição antes de mover trabalho entre camadas Entenda o caminho da solicitação antes de editá-lo: 1. Uma solicitação externa entra na API e no aplicativo de painel. 2. Os serviços validam a intenção e chamam o mecanismo de ciclo de vida da execução. 3. O mecanismo persiste o estado e enfileira o trabalho. 4. Um supervisor reivindica o trabalho e gerencia a execução isolada. 5. Os resultados retornam pelo mecanismo de ciclo de vida. 6. O estado transacional e os eventos analíticos fluem para seus armazenamentos separados. Mantenha SDKs públicos, ferramentas de linha de comando, tipos compartilhados, extensões de compilação, ganchos de cliente, trabalhadores de fila, bancos de dados, análises, agendamento e mecanismos de execução nos pacotes declarados. Importe tipos públicos compartilhados por subcaminhos compatíveis, em vez de raízes amplas de pacotes, quando o contrato de exportação exigir. Não mova responsabilidades entre essas camadas por conveniência. Uma alteração no agendamento, enfileiramento, execução ou persistência deve considerar toda a transição de estado e o caminho de falha. ## Não reative o motor de execução desativado e recuse clientes antigos com um erro limpo Quando um mecanismo antigo tiver sido removido, nomes históricos de diretórios ou enums de compatibilidade não comprovam que ele ainda esteja em execução. Trate a documentação da arquitetura atual e o grafo de pacotes ativo como fontes oficiais. Nunca reintroduza o caminho desativado para atender a um branch ou uma solicitação antiga. O tratamento de compatibilidade pode reconhecer uma versão obsoleta somente para rejeitá-la ou finalizá-la de forma controlada com um erro do cliente; não deve encaminhar trabalho para código de execução inexistente nem transformar uma rejeição esperada em falha do servidor. Antes de alterar o comportamento de compatibilidade: - Rastreie a seleção do mecanismo ativo. - Confirme como os clientes obsoletos são identificados. - Preserve uma semântica de erros clara. - Adicione testes tanto para o caminho atual quanto para a rejeição da versão desativada. Mantenha orientações de SDK versionadas e regras de agentes geradas em sua etapa de manutenção dedicada. Não atualize conjuntos distribuídos de instruções, a menos que a tarefa os inclua explicitamente. ## Escreva tarefas com o SDK público atual e atualize a documentação quando ele mudar Defina tarefas duráveis por meio do ponto de entrada atual do SDK público. Não importe subcaminhos de versões obsoletas nem reative uma API descontinuada de definição de trabalhos. Uma definição de tarefa deve ter: - Um identificador estável. - Um contrato de entrada tipado. - Uma função assíncrona de execução. - Erros explícitos para entradas inválidas. - Comportamento idempotente ou um limite documentado de novas tentativas para efeitos colaterais. Trate o código empacotado nas imagens de execução dos clientes como código público do ambiente de execução, mesmo quando ele tiver origem no pacote de linha de comando. Verifique em conjunto as exportações do pacote, as dependências empacotadas e o comportamento do contêiner. Atualize a documentação pública e os exemplos quando o contrato do SDK mudar. Mantenha a documentação do produto no site designado e siga as regras locais de formatação e navegação desse site. ## Execute uma tarefa real do início ao fim com uma build local Use um projeto de referência mantido para testar alterações no SDK e na plataforma com uma compilação local. Vincule o projeto de referência aos pacotes do espaço de trabalho, em vez de testar por engano um pacote lançado. Execute o fluxo na ordem: 1. Inicie os serviços necessários de armazenamento e fila. 2. Aplique as migrações do banco de dados e insira os dados iniciais da organização e do projeto de referência. 3. Compile o SDK, a ferramenta de linha de comando e os pacotes afetados. 4. Inicie o aplicativo de API em segundo plano e verifique seu endpoint de integridade. 5. Inicie o trabalhador local de tarefas a partir do projeto de referência vinculado. 6. Aguarde um sinal explícito de que o trabalhador está pronto. 7. Acione uma tarefa representativa por meio da interface de controle compatível. 8. Consulte ou liste as execuções até que o estado terminal esperado apareça. 9. Inspecione o resultado retornado e o estado persistido da execução. Não informe sucesso de ponta a ponta com base apenas na compilação. Preserve a saída dos comandos ou os identificadores das execuções como evidência e interrompa os processos em segundo plano ao concluir a verificação. ## Fixe imagens de contêiner multiplataforma e retire as marcas de depuração antes do merge Fixe as imagens de contêiner em digests de índices multiplataforma, não em digests de imagens específicos de arquitetura. Selecione o digest na página de lançamento da imagem que seja neutra em relação à plataforma para que o desenvolvimento e a integração contínua resolvam a arquitetura correta. Use marcadores estruturados de depuração durante o desenvolvimento de fluxos distribuídos: - Adicione marcadores em transições de estado, limites de fila e chamadas externas. - Use somente namespaces registrados do aplicativo; não invente um novo namespace sem aprovação. - Limpe os rastros existentes antes de reproduzir um defeito. - Consulte com limites e paginação por cursor. - Mantenha marcadores temporários no branch de desenvolvimento enquanto a investigação estiver ativa. - Remova marcadores e importações antes da mesclagem. Os revisores não devem sinalizar instrumentação temporária reconhecida apenas por ela existir no branch. Devem verificar que ela não possa chegar à produção e que a etapa de remoção faça parte da conclusão. ## Execute só as verificações que cabem na alteração e informe o que foi omitido Antes da entrega, inspecione todo o conjunto de arquivos alterados e execute somente as barreiras aplicáveis: - Formatador, correção de lint e lint somente leitura. - Verificação de tipos para aplicativos e pacotes privados. - Compilações reais para pacotes publicados. - Testes focados com contêineres de serviço descartáveis. - Um registro de alteração de pacote ou nota do servidor no limite correto. - Versões exatas fixadas de dependências compartilhadas. - Testes do mecanismo atual e da versão desativada quando o roteamento mudar. - Um digest de imagem multiplataforma quando as referências de imagem mudarem. - Uma execução do projeto de referência vinculado quando o SDK ou o comportamento de execução mudar. - Remoção da instrumentação temporária de depuração antes da mesclagem. Informe o que foi executado, o que passou e qualquer barreira omitida intencionalmente, com o respectivo motivo. Não alegue a correção do ambiente de execução, do pacote ou do contêiner com base em uma verificação mais fraca que não consiga observá-la.