Boas práticas para a modernização do GitHub Copilot

Siga estas orientações para obter os melhores resultados da modernização do GitHub Copilot ao atualizar e migrar projetos .NET.

Antes de começar

Prepare os seus projetos antes de iniciar uma atualização para obter os melhores resultados.

Verifique se as compilações e testes da sua solução são aprovados.

O agente valida as alterações que faz ao executar builds e testes. Se a sua solução já estiver quebrada antes de começar, o agente não consegue distinguir falhas pré-existentes dos problemas que introduziu.

Documente scenario-instructions.md quaisquer falhas conhecidas nos testes para que o agente saiba que deve ignorá-las.

Compromete-se ou guarde trabalho não comprometido

Comece com um diretório limpo e funcional para evitar misturar as alterações não comprometidas com as modificações do agente. Uma base limpa facilita a revisão ou reverter alterações.

git stash
git status

Fazer backup de repositórios não-Git

O agente também trabalha com pastas que não estão sob controlo de versão. Se o teu projeto não estiver num repositório Git, o agente salta operações de branch e commit. Se sim, faça uma cópia de segurança da pasta do projeto antes de começar para a poder restaurar se necessário.

Considere inicializar um repositório Git local antes de iniciar a atualização, mesmo que não envie para um fornecedor cloud. Um repositório Git local permite-lhe:

• Reverter alterações individuais com git revert.
• Acompanha o progresso da atualização passo a passo no histórico de commits.
• Controla quais alterações guardar ou descartar.
• Mantém o teu código original seguro no ramo principal enquanto o agente trabalha num ramo separado.

cd your-project-folder
git init
git add .
git commit -m "Baseline before upgrade"

Revise a sua cobertura de testes

O agente depende de testes para validar que as suas alterações não quebram o comportamento. Projetos com boa cobertura de testes recebem atualizações com maior confiança.

Comece pequeno

Se for a sua primeira vez a usar o agente, escolha um projeto pequeno e de baixo risco como piloto. Uma biblioteca de classes ou um projeto utilitário é o ideal. Começar pequeno permite-lhe perceber o fluxo de trabalho, ganhar confiança e descobrir quaisquer problemas específicos do repositório antes de abordar a sua aplicação principal.

Durante a atualização

Siga estas orientações enquanto o agente trata da sua atualização.

Usa o modo guiado para a tua primeira melhoria

O agente suporta tanto modos guiados como automáticos. No modo guiado, o agente faz pausas em pontos-chave de decisão para a sua revisão e aprovação. Começa pelo modo guiado para perceberes o que o agente faz e porquê. Muda para o modo automático assim que te sentires confortável com o fluxo de trabalho.

Revise cuidadosamente a avaliação

A avaliação é a sua melhor oportunidade para detetar problemas antes que o agente comece a fazer alterações. Procure:

• Projetos que o agente pode ter perdido ou identificado mal.
• Dependências que sabes que são problemáticas.
• Há qualquer coisa invulgar na sua solução que o agente deva saber.

Se detetar algo, diga ao agente no chat ou adicione a informação a scenario-instructions.md. Também pode editar assessment.md diretamente para adicionar contexto, corrigir projetos mal identificados ou assinalar preocupações antes de o agente avançar para o planeamento.

Dedica tempo à fase de planeamento

O agente gera um plano com base na sua avaliação. Revise o plano antes de prosseguir:

• A ordem faz sentido para a tua base de código?
• Existem dependências que o agente pode não conhecer?
• Algum projeto deve ser excluído ou tratado de forma diferente?

Peça ao agente para reordenar tarefas, saltar projetos ou alterar a sua abordagem. Conheces melhor a tua base de código do que o agente, por isso usa esse conhecimento. Edite o plan.md ficheiro diretamente para ajustar a ordem das tarefas, adicionar tarefas ou remover tarefas.

Dê feedback imediatamente

O agente aprende com as suas correções durante uma sessão. Se o agente fizer uma escolha com a qual não concorda:

• Diz-lhe já: "Não uses esse padrão, usa X em vez disso."
• Adicione orientações persistentes a scenario-instructions.md para que o agente se lembre entre tarefas e sessões.

Mantenha-se envolvido durante a execução

A execução não é intervenção. Antes de indicar ao agente para iniciar, reveja tasks.md:

• A ordem das tarefas faz sentido para a sua base de código?
• Há tarefas que queres saltar ou reordenar?
• Falta alguma tarefa?

Peça ao agente para ajustar a lista de tarefas ou editar tasks.md diretamente antes de começar a execução. Assim que a execução começar, se o agente fizer uma má decisão a meio da tarefa, avise-a imediatamente — aplica a sua correção daqui para a frente.

Conheces melhor a tua base de código do que o agente, por isso usa esse conhecimento em todas as fases.

Dificuldades comuns

Fique atento a estes problemas comuns que podem atrasar ou complicar uma atualização.

Grandes soluções com 50+ projetos

O agente trabalha projeto a projeto, por isso soluções grandes demoram tempo. Seja paciente e acompanhe o progresso. Considere começar com um projeto representativo de ponta a ponta antes de se comprometer com a solução completa. Um projeto-piloto único identifica questões sistémicas desde cedo.

Feeds privados NuGet

Para feeds NuGet privados, autentique antes de iniciar a atualização (por exemplo, através do fornecedor de credenciais ou configuração do feed da sua organização). Sem autenticação, falhas na restauração de pacotes bloqueiam o progresso.

Destinos e importações personalizados do MSBuild

Personalizações complexas de compilações, como ficheiros personalizados .targets , importações condicionais ou lógica de compilação não padrão, podem confundir a avaliação e causar falhas inesperadas na compilação. Se a tua solução tiver estas personalizações, menciona-as no chat ou em scenario-instructions.md para que o agente as possa ter em conta.

Tempos limite da sessão

As atualizações de longa duração podem abranger várias sessões. O agente acompanha o seu progresso em ficheiros de workflow (em .github/upgrades/), para poder retomar de onde parou. Quando começares uma nova sessão, menciona onde estavas: "Continua a atualização do .NET 10. Estava no meio do projeto Data.Access."

Colabore eficazmente

A qualidade da sua interação afeta diretamente a qualidade dos resultados.

Seja específico quanto ao âmbito

Quanto mais específico for, melhor desempenho o agente:

Partilha as tuas limitações

Informe o agente sobre as limitações do mundo real desde o início:

• "Não podemos quebrar a compatibilidade retroativa para a API pública."
• "Temos um prazo de lançamento daqui a duas semanas, por isso dá prioridade aos projetos web."
• "O módulo de reporte legado deve ser excluído desta atualização."

Explica a tua arquitetura

O agente analisa a estrutura do código, mas não conhece o modelo mental da tua equipa. Ajude o agente a compreender:

• "Project A é a nossa biblioteca partilhada. B, C e D dependem disso."
• "O projeto WebApi é a nossa API voltada para o público; Internal.Api é apenas para serviços internos."
• "O projeto Modelos é gerado automaticamente a partir da nossa especificação OpenAPI. Não a modifiquem diretamente."

Pergunte porquê

O agente pode explicar o raciocínio. Se uma decisão não parecer correta, pergunte:

• "Porque escolheste a ordem de baixo para cima?"
• "Porque é que estás a atualizar este pacote para a versão X em vez da Y?"
• "Porque é que dividiste isto em subtarefas?"

Compreender o raciocínio ajuda-te a dar melhor feedback.

Guardar preferências cedo

Se tens fortes preferências sobre estilo de programação, padrões ou abordagens, adiciona-as scenario-instructions.md logo na primeira sessão. Este ficheiro persiste entre as sessões e está sempre no contexto do agente, tornando-o a forma mais fiável de influenciar o comportamento.

Recuperar de problemas

Usa estas estratégias quando a atualização não correr como esperado.

Falhas de compilação após uma tarefa

Diz ao agente: "A build está a falhar depois da última tarefa." O agente analisa o erro e tenta corrigi-lo. Se o agente não conseguir resolver o problema:

1. Forneça uma correção manual e diga ao agente o que foi feito. O agente aprende com a sua solução.
2. Reverte o commit (git revert ou redefine para o commit anterior) e peça ao agente para tentar um método diferente.
3. Ignora a tarefa problemática e volta a ela mais tarde.

Estratégia errada escolhida

Se a abordagem geral do agente não funcionar para a sua base de código, reinicie a fase de planeamento:

• Vamos refazer o plano. Quero atualizar primeiro os projetos web em vez de de baixo para cima."
• "Muda a estratégia para atualizar todas as bibliotecas partilhadas num só lote."

Agente preso num ciclo

Se o agente repetir a mesma correção sem progresso, diga "Pare" e descreva o que está a observar, ou interrompa a sessão manualmente. O agente pode reiniciar a sua abordagem e tentar algo diferente.

Desfazer todas as alterações

Se usaste um ramo Git para a atualização, desfaz tudo voltando ao ramo original:

git checkout your-original-branch
git branch -D upgrade-branch

O teu código original está intacto. Se estiver a trabalhar sem controlo de versão, restaure a partir do backup que fez antes de começar.

Segurança e privacidade

• excertos de código: GitHub Copilot processa os excertos de acordo com a política de privacidade do GitHub Copilot e não os mantém para além da sessão atual.
• Os ficheiros de workflow (scenario-instructions.mdtarefas personalizadas, preferências) permanecem no seu repositório em .github/upgrades/. O GitHub não transmite estes ficheiros para serviços externos.
• A .github/upgrades/ pasta faz parte do teu repositório. Realiza o commit na pasta, pois contém o progresso e o estado da atualização. O agente precisa da pasta para retomar o trabalho entre sessões. Podes removê-lo depois da atualização estar concluída.
• Telemetria: Desativar através das definições de telemetria do seu IDE.

Sugestões de desempenho

• Fechem ficheiros e separadores desnecessários: O agente analisa o espaço de trabalho ativo, e menos ficheiros abertos significa menos ruído.
• Atualize em fases para soluções muito grandes: Em vez de atualizar todos os projetos de uma vez, agrupe-os. Por exemplo, atualize primeiro todas as bibliotecas, depois todos os projetos web e depois os testes.
• Use cache de compilações: O agente executa muitas compilações incrementais durante a validação. Os caches de build quentes tornam a validação significativamente mais rápida. Evita limpar a saída da compilação entre tarefas.

Conteúdo relacionado

• O que é a modernização do GitHub Copilot?
• Atualize uma aplicação .NET com a modernização pelo GitHub Copilot
• Conceitos fundamentais
• Resolução de problemas na modernização do GitHub Copilot