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 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. Edite 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 errar durante a tarefa, informe-o 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