Faça alterações importantes na documentação do Microsoft Learn

Importante

Todos os repositórios que publicam no Microsoft Learn adotaram o Código de Conduta de Código Aberto da Microsoft ou o Código de Conduta do .NET Foundation. Para obter mais informações, veja Code of Conduct FAQ (FAQs do Código de Conduta). Em alternativa, contacte opencode@microsoft.com ou conduct@dotnetfoundation.org relativamente a dúvidas ou comentários.

Pequenas correções ou esclarecimentos à documentação e exemplos de código em repositórios públicos são cobertos pelos learn.microsoft.com Termos de Uso. Quaisquer alterações gerarão um comentário na solicitação pull, solicitando que você envie um Contrato de Licença de Contribuição (CLA) online se você não for um funcionário da Microsoft. Para intercalar o pedido Pull, deve preencher o formulário online.

Este artigo mostra como alterar um artigo do Microsoft Learn usando ferramentas locais e é adequado para um colaborador que precisa fazer uma grande alteração ou será um colaborador frequente de um repositório. Os colaboradores frequentes normalmente têm alterações contínuas ou de longa duração que passam por vários ciclos de compilação/validação/preparo ou se estendem por vários dias antes de assinarem sua solicitação pull (PR).

Exemplos destes tipos de contribuições:

• Fazer uma grande contribuição. Por exemplo, suas contribuições (adições, alterações ou exclusões) podem abranger vários artigos e precisam ser comprometidas e testadas como uma unidade de trabalho em um único RP.
• Criar e publicar um novo artigo, o que geralmente requer um editor local mais robusto.
• Adicionar novas imagens ou atualizar imagens, o que normalmente requer que você crie simultaneamente um novo media subdiretório, crie arquivos de imagem, atualize links de imagem em artigos e visualize arquivos Markdown em um editor local para testar a renderização de imagens.
• Atualizar um artigo durante alguns dias antes de publicar. Nesses casos, você normalmente precisa fazer a integração regular de outras alterações que ocorrem na ramificação padrão. Esta integração é mais fácil de efetuar através do Git Bash e da edição local. Você também corre o risco de perder suas edições se fizer isso através do editor da web do GitHub e esperar antes de confirmar as alterações.
• Fazer atualizações contínuas no mesmo artigo após a abertura de um RP. Embora você possa usar o editor da Web do GitHub para essa finalidade, você pode criar vários PRs pendentes para o mesmo arquivo, que podem entrar em conflito entre si.

Pré-requisitos

• Identifique o repositório GitHub que armazena a documentação que você deseja editar.
• Crie uma conta no GitHub, se não tiver uma.
• Instale as ferramentas Git e Markdown.
• Configure um repositório Git local.
• Analise os fundamentos do Git e do GitHub (opcional).

Crie e confira seu ramo de trabalho

Para começar, crie uma nova ramificação de trabalho em seu repositório local para capturar as alterações propostas. Para obter mais informações sobre ramificações, consulte Fundamentos do Git e do GitHub.

Este tutorial usa o Git Bash e o Visual Studio Code, mas você pode usar qualquer cliente e editor Git de sua preferência.

1. No VS Code, abra a pasta do repositório do seu clone local. No menu Arquivo, selecione Abrir pasta e navegue até a pasta em sua máquina.

2. Selecione Ver no menu superior e, em seguida, selecione Terminal para abrir o terminal integrado.

3. No terminal integrado, certifique-se de que está na pasta do repositório.

4. Antes de criar uma ramificação de trabalho, certifique-se de que sua ramificação principal local esteja atualizada com tudo na ramificação principal do repositório de produção. Essa tarefa garante que sua ramificação de trabalho capture todas as alterações que aconteceram no repositório de produção desde a última vez que você sincronizou com ele.

   1. Alterne para a ramificação principal em seu repositório local:

      git checkout main 
      

   2. Certifique-se de que sua filial principal local esteja atualizada:

      git pull upstream main 
      

5. Crie uma ramificação de trabalho local com base no principal:

   git checkout -b <branch-name>
   

   <branch-name> é um espaço reservado. Ao executar o comando, substitua-o por um nome exclusivo e significativo para sua ramificação e remova os colchetes angulares.

6. Empurre a ramificação de trabalho local para a ramificação remota na bifurcação do GitHub:

   git push origin <branch-name> -u
   

   A opção -u liga as ramificações locais e remotas. Esta opção permite que você pressione commits para sua bifurcação digitando apenas git push em vez de git push origin <branch-name>.

Localizar o arquivo Markdown de origem

Para editar um artigo, localize o arquivo de origem do artigo no clone do repositório local. Dentro do VS Code, acesse os arquivos Markdown do repositório através do explorador de arquivos (um ícone de documento na barra lateral superior esquerda). O explorador de arquivos mostra a estrutura de pastas do repositório e você pode navegar até o arquivo que deseja editar.

Se não conseguir encontrar o ficheiro, visite o artigo sobre o Microsoft Learn e selecione o ícone Editar lápis. O local da pasta relativa no repositório GitHub é exibido na URL. Aqui está um exemplo de URL de link de edição :

   https://github.com/Microsoft/azure-docs/blob/main/articles/azure-functions/functions-overview.md

Eis um exemplo de localização de ficheiro para este URL.

   C:\GitHub\*\azure-docs\articles\azure-functions\functions-overview.md

Editar o ficheiro

1. Abra o arquivo no VS Code selecionando-o.
2. Faça as suas alterações.
3. Salve suas alterações selecionando Salvar arquivo>. Use Salvar tudo para salvar vários arquivos de uma só vez.

Confirme e promova as suas alterações

Se você fez edições substanciais ou revisou um artigo quanto à atualização, atualize ms.date no bloco de metadados na parte superior do arquivo. Formate a data como mm/dd/aaaa.

Você pode usar o terminal VS Code ou a interface do usuário do VS Code para confirmar e enviar suas alterações.

VS Code Terminal

1. Execute o git status comando para verificar se apenas os arquivos editados aparecem na lista de arquivos alterados.

   git status
   

2. Execute o comando seguido do caminho do arquivo e do nome do arquivo para preparar o git add arquivo alterado.

   git add folder-name/file-name.md
   

   Se você alterou vários arquivos, insira um git add comando para cada arquivo.

   Como alternativa, você pode executar git add . (observe o período após add) para configurar automaticamente todas as alterações feitas. Este método é mais rápido, mas pode causar problemas ao incluir alterações feitas por acidente.

3. Execute git status novamente para confirmar quais alterações foram preparadas.

4. Execute o git commit comando seguido de uma mensagem de confirmação para salvar as alterações no repositório clonado local.

   git commit -m "your commit message"
   

5. Execute git push para enviar suas alterações.

   git push
   

Interface do usuário do VS Code

Você pode criar e enviar por push uma confirmação usando os recursos de integração do Git do VS Code. Lembre-se de continuar o seu trabalho na mesma máquina. Se mudar de máquina, não terá a versão mais recente do ramo de trabalho para continuar.

1. Certifique-se de que seu repositório local ainda tenha a mesma ramificação de trabalho com check-out. Na interface do usuário do VS Code, a ramificação é mostrada no canto inferior esquerdo. O nome da filial também funciona como um botão para alternar ramificações.

   

2. Na barra lateral esquerda do VS Code, selecione a ferramenta fork para ver o painel Source Control: Git .

   

   O ficheiro que editou aparece em Alterações com um M à direita para indicar que foi modificado. Novos arquivos aparecem com um U (não rastreado) e arquivos excluídos aparecem com um D.

3. Encene as mudanças. Passe o cursor sobre a linha Alterações até aparecer um + ícone. Selecione esse ícone. Esta ação é equivalente ao git add comando. O arquivo agora aparece na seção Alterações em etapas.

4. Insira uma mensagem de confirmação, como "atualizar data de metadados" na caixa de texto Mensagem, e selecione a marca de seleção.

   

5. Empurre a confirmação. Selecione o botão Sincronizar alterações que aparece abaixo do bloco de mensagens de confirmação.

   

Já está! Seu código agora está em seu repositório GitHub e pronto para você abrir um PR.

Precisa de corrigir algo que enviou? É fácil! Basta repetir as etapas acima, começando com Editar o arquivo, para fazer alterações na mesma ramificação e, em seguida, confirmar e enviar novamente (não há necessidade de configurar o servidor upstream em pushes subsequentes da mesma ramificação). Geralmente, as ramificações são usadas para separar fluxos de trabalho, portanto, você não precisa criar uma nova ramificação, a menos que esteja pronto para trabalhar em outra coisa.

Faça a sua próxima alteração

Pronto para fazer outra mudança, sem relação com esta? Volte para a ramificação padrão, extraia do repositório upstream para atualizar sua bifurcação e faça check-out de uma nova ramificação. Execute os seguintes comandos no Git Bash:

git checkout main
git pull upstream main
git checkout -b "branchname"
git push origin <branch-name> -u

Agora você está em uma nova ramificação vinculada à sua filial remota e está pronto para fazer mais alterações. Você está no caminho certo para se tornar um colaborador especializado!

Próximos passos

• Se você concluiu as etapas acima, agora é hora de abrir um PR para mesclar suas alterações na ramificação principal.
• Para saber mais sobre tópicos como a sintaxe das extensões Markdown e Markdown, revise a referência Markdown.