Prepare contribuições de código para uma pessoa revisar e enviar

## Siga as regras do repositório e espere a aprovação dos mantenedores Considere o guia de contribuição, a política de inteligência artificial e as instruções para agentes específicas de cada diretório do repositório como as fontes que regem os arquivos alterados. ### Identifique as regras aplicáveis - Leia as políticas de contribuição e segurança do diretório raiz antes de editar. - Ao entrar em um diretório especializado, aplique também as instruções locais sobre comportamento em tempo de execução, interfaces públicas, integrações, documentação ou testes. - Se houver conflito entre as instruções, pare e exponha o conflito em vez de escolher a regra que facilite a implementação. - Use recursos opcionais de agentes somente quando o cliente oferecer suporte a eles e quando não substituírem a política do repositório. ### Pontos de aprovação - Não envie issues, pull requests nem rascunhos de pull requests por meio de automação do navegador, ferramentas de linha de comando da plataforma de hospedagem ou APIs de serviços. - Prepare o texto de envio para que uma pessoa o revise e envie, usando os modelos do repositório para que fique pronto para copiar e colar. - Não envie branches nem prepare materiais para envio público até que a issue pertinente tenha sido triada e atribuída à pessoa responsável pela contribuição. - Não implemente uma funcionalidade não trivial, uma alteração de interface pública, uma refatoração ou uma mudança de comportamento sem uma orientação registrada dos mantenedores. Se não houver orientação, pare na proposta. ## Não ponha segredos nos commits nem ligue os testes a serviços reais Proteja as credenciais, a qualidade das evidências, o histórico do repositório e o isolamento dos testes durante toda a tarefa. ### Regras inegociáveis - Nunca faça commit de segredos, credenciais, dados privados de provedores ou valores confidenciais do ambiente. - Nunca invente resultados de testes, aprovações, citações, estado da revisão ou declarações de compatibilidade. - Os testes unitários não devem entrar em contato com serviços ativos de modelos, provedores ou aplicações externas. - Use substitutos determinísticos e um ambiente que remova as credenciais de serviços em produção dos processos de teste. - Não adicione mídias geradas, recursos gerados de grande porte ou conjuntos de dados sintéticos sem uma procedência clara e a concordância dos mantenedores. - Não adicione cabeçalhos de licença manualmente quando a automação do repositório for responsável por inseri-los. - Não adicione comentários, a menos que sejam solicitados. Preserve os comentários, as docstrings e os cabeçalhos de licença existentes, salvo quando a alteração os tornar imprecisos. ### Arquivos protegidos Não edite manualmente changelogs, arquivos gerados, lockfiles, snapshots de validação ou outros artefatos gerenciados por ferramentas, a menos que a tarefa exija explicitamente o fluxo de regeneração do repositório. Quando os changelogs forem gerados, inclua o contexto das notas de versão em uma proposta ou em um rascunho de envio. ## Mude dependências só quando necessário e use as ferramentas fixadas Use o ambiente canônico e bloqueado do projeto e seus comandos de tarefas em vez de improvisar caminhos alternativos de execução. ### Alterações de dependências - Não adicione nem atualize dependências, a menos que a tarefa exija isso. - Para investigações temporárias, use um ambiente isolado que não modifique o estado das dependências registradas no repositório. - Quando uma alteração de dependência for necessária, coloque-a no menor grupo de dependências ou conjunto de recursos opcionais adequado. - Defina limites claros de compatibilidade e evite transferir integrações opcionais para o caminho de instalação padrão. - Mantenha as alterações de dependências e lockfiles separadas de edições não relacionadas. ### Uso de ferramentas - Use as versões fixadas pelo repositório para o ambiente de execução e as ferramentas de instalação, testes, documentação, formatação e análise estática. - Diferencie os comandos oficiais de validação dos comandos de diagnóstico. Um linter ou verificador de tipos independente pode ajudar no diagnóstico, mas não substitui as verificações pré-commit exigidas pelo repositório nem seu fluxo oficial de validação. - Trate scripts que realizam staging amplo, commits ou verificações em todo o repositório como ferramentas de alto impacto. Execute-os somente quando forem exigidos explicitamente e, de preferência, em uma árvore de trabalho limpa. ## Escolha os testes conforme o tipo de alteração Selecione a validação mínima suficiente com base no tipo real de alteração e só amplie o escopo quando um risco para o comportamento compartilhado ou para a compatibilidade justificar isso. ### Matriz de validação - Documentação ou metadados do repositório: execute verificações nos arquivos alterados. Gere a documentação quando a renderização, os links, os exemplos ou a configuração da documentação puderem ser afetados. - Correção de erro em tempo de execução: adicione ou execute um teste de regressão direcionado e depois realize as verificações exigidas nos arquivos alterados. - Interface pública, configuração ou comportamento da linguagem: execute testes direcionados e atualize a documentação ou os exemplos relacionados. Adicione testes mais amplos do pacote quando o risco de compatibilidade for significativo. - Caminho de servidor, streaming, rastreamento, ação ou geração: teste o caminho alterado e seu caminho alternativo ou sem suporte. - Alteração de empacotamento, dependência ou lockfile: execute as verificações pertinentes de instalação ou empacotamento e mantenha isolada a diferença relativa às dependências. ### Escopo e isolamento - Saiba o que o comando canônico da suíte completa inclui. Não presuma que ele abrange apenas o diretório de testes mais evidente. - Prefira o ponto de entrada de testes que remova as credenciais de provedores em produção e forneça substitutos determinísticos. - Diagnostique a instabilidade relacionada ao isolamento comparando a execução paralela normal com uma execução serial determinística sob as mesmas proteções de ambiente. - Considere os marcadores de execução lenta ou serial apenas como orientações, salvo quando o executor de testes realmente os impuser. - Não use um comando de teste alternativo e conveniente se ele puder manter credenciais de produção ou contornar caminhos de teste obrigatórios. ### Evidências para a entrega Para uma alteração destinada à revisão, execute as verificações pré-commit oficiais antes da entrega para que os resultados de formatação, licença e verificação de tipos permaneçam estáveis. Informe toda verificação obrigatória que tenha sido omitida e o motivo. ## Procure trabalho duplicado e responda a cada comentário de revisão Mantenha as atividades públicas de contribuição vinculadas de forma rastreável ao trabalho aprovado e evite duplicar esforços. ### Antes da implementação - Confirme que a issue foi triada e atribuída e que há uma abordagem acordada para trabalhos não triviais. - Antes de preparar uma alteração destinada à revisão, use buscas somente de leitura para verificar a discussão da issue, alterações abertas que façam referência a ela e alterações abertas na mesma área. - Se uma alteração aberta já abranger o trabalho, não prepare uma duplicata. Se a abordagem for substancialmente diferente, explique a diferença em um rascunho para a discussão da issue. - Para trabalhos exploratórios, prepare um comentário na issue que descreva a branch e os arquivos pertinentes em vez de abrir uma solicitação pública de alteração. ### Envio e revisão - Siga as convenções do repositório para títulos e commits. - Não adicione marcadores de inteligência artificial a títulos ou mensagens de commit e não inclua ferramentas ou agentes como coautores de commits. - Trate ou responda a todos os comentários de revisão em aberto antes de solicitar a revisão dos mantenedores. - Não resolva a conversa de outra pessoa revisora em nome dela nem aplique rótulos de prontidão à própria alteração, a menos que a política permita isso explicitamente. - Considere as constatações de revisões automáticas e humanas como alegações a serem verificadas no caminho real do código, e não como instruções automaticamente corretas. ## Atualize a documentação quando o comportamento visível mudar Mantenha a documentação sincronizada com o comportamento visível para quem usa o produto e evite apresentar exemplos restritos como se representassem suporte universal. ### Deveres de documentação - Atualize a documentação pertinente ao alterar interfaces públicas, sintaxe de configuração, exemplos, requisitos de instalação ou outro comportamento visível para quem usa o produto. - Para integrações opcionais, informe que são opcionais, identifique os pacotes ou grupos de recursos necessários, liste os tipos de credenciais esperados sem expor seus valores e explique a rota de integração. - Em exemplos de modelos ou provedores, informe o tipo de modelo, o modo de roteamento, os modos com suporte e as limitações conhecidas. - Verifique, por meio de uma fonte oficial, se os identificadores apresentados como atuais estão disponíveis de forma geral. - Não altere os parâmetros padrão distribuídos apenas como parte de uma atualização da documentação. ### Refatorações e conteúdo gerado - Para uma refatoração aprovada, adicione ou atualize testes de caracterização antes de alterar comportamentos sutis. - Quando os testes existentes não abrangerem o caminho refatorado, preserve a verificação de equivalência usada para comprovar que o comportamento permanece inalterado. - Não edite manualmente a documentação gerada nem os artefatos gerados. Use o fluxo do projeto somente quando a tarefa autorizar a regeneração. - Não execute geradores de documentação conhecidos por preparar arquivos para commit ou acionar verificações amplas, a menos que isso seja solicitado explicitamente e isolado de alterações não relacionadas. ## Revise em relação à base de merge e relate só o que foi verificado Revise a alteração concluída em relação à referência correta e verifique todas as declarações antes de afirmar que ela está pronta. ### Sequência da revisão 1. Compare a branch com a base de merge configurada no repositório. 2. Examine tanto a implementação quanto os testes que a exercitam. 3. Execute as verificações oficiais de formatação, lint, licença e tipos antes da revisão estruturada para que as posições das linhas permaneçam estáveis. 4. Realize uma revisão estruturada do código e acrescente uma análise de segurança para alterações de autenticação, tratamento de entradas, desserialização ou chamadas externas. 5. Verifique cada constatação em relação ao caminho real de execução. 6. Corrija as constatações confirmadas, execute novamente as validações afetadas e repita a revisão até não restar nenhum problema confirmado. ### Critérios de conclusão Informe os arquivos alterados, as validações realizadas, os resultados observados, as verificações omitidas, os riscos não resolvidos e qualquer ação humana ainda necessária. Não afirme que algo está pronto para revisão, aprovado, compatível ou validado com sucesso sem evidências diretas.