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 Software Livre da Microsoft ou o Código de Conduta de .NET Foundation. Para obter mais informações, confira as Perguntas frequentes sobre o Código de conduta. Ou entre em contato com opencode@microsoft.com ou conduct@dotnetfoundation.org com perguntas ou comentários.

Pequenas correções ou esclarecimentos na documentação e nos exemplos de código em repositórios públicos são regidos pelos Termos de Uso do learn.microsoft.com. Quaisquer alterações gerarão um comentário na pull request, pedindo o envio de um Contrato de Licença de Contribuição (CLA) online, caso você não seja um funcionário da Microsoft. Será necessário completar o formulário online antes de sua pull request poder ser mesclada.

Este artigo mostra como alterar um artigo do Microsoft Learn usando ferramentas locais, e é adequado para um contribuidor que precise fazer uma alteração importante ou que será um contribuidor frequente de um repositório. Os contribuidores frequentes normalmente fazem alterações constantes (execução prolongada), que passam por vários ciclos de build/validação/preparo ou que duram vários dias, antes da aprovação da pull request (PR).

Entre os exemplos desses tipos de colaborações estão:

• Fazendo uma grande contribuição. Por exemplo, você pode fazer contribuições (adições, alterações ou exclusões) que abrangem diversos artigos e precisam ser confirmadas e testadas como uma unidade de trabalho em uma única PR.
• Criando e publicando um novo artigo, o que normalmente requer um editor local mais robusto.
• Adicionar novas imagens ou atualizar imagens, o que normalmente requer a criação simultânea de um subdiretório media, a criação de arquivos de imagens, atualizações de links de imagens em artigos e preview de arquivos Markdown em um editor local para testar a renderização da imagem.
• Atualizar um artigo por um período de dias antes de publicar. Nesses casos, normalmente é necessário fazer a integração regular de outras alterações que ocorrem no branch padrão. Essa integração é mais fácil por meio de Bash do Git e edição local. Você também correrá o risco de perder suas edições caso faça isso por meio do editor Web do GitHub e aguarde antes de confirmar as alterações.
• Fazer atualizações contínuas no mesmo artigo depois que uma PR foi aberta. Embora você possa usar o editor Web do GitHub para essa finalidade, você pode acabar criando várias PRs pendentes para o mesmo arquivo, que podem entrar em conflito umas com as outras.

Pré-requisitos

• Identifique o repositório do GitHub que armazena a documentação que deseja editar.
• Criar uma conta gratuita no GitHub, caso ainda não tenha uma.
• Instalar ferramentas do Git e do Markdown
• Configurar um repositório Git local
• Revisar os conceitos básicos do Git e do GitHub (opcional)

Crie e faça check-out do seu branch 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 clone local. No menu Arquivo, selecione Abrir pasta e navegue até a pasta em seu computador.

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

3. No terminal integrado, verifique se você está na pasta do repositório.

4. Antes de criar um branch de trabalho, verifique se a ramificação principal local está atualizada com tudo na ramificação principal do repositório de produção. Essa tarefa garante que seu branch 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. Verifique se a ramificação principal local está atualizada:

      git pull upstream main 
      

5. crie um branch 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 seu branch e remova os colchetes angulares.

6. Envie o branch de trabalho local para o branch remoto no seu fork do GitHub:

   git push origin <branch-name> -u
   

   A opção -u vincula branches locais e remotos. Esta opção permite que você transmita confirmações para o seu fork digitando apenas git push em vez de git push origin <branch-name>.

Procurar o arquivo Markdown de origem

Para editar um artigo, procure 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 arquivo, visite o artigo no Microsoft Learn e selecione o ícone de lápis Editar. O local relativo da pasta no repositório do GitHub é exibido na URL. Veja um exemplo de URL de link de edição:

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

Aqui está um exemplo de local de arquivo para essa URL.

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

Edite o arquivo

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

Confirmar e transmitir alterações

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

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

Terminal do VS Code

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

   git status
   

2. Execute o comando git add seguido pelo caminho do arquivo e nome do arquivo para preparar o arquivo que você alterou.

   git add folder-name/file-name.md
   

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

   Como alternativa, você pode executar git add . (observe o período após add) para preparar automaticamente todas as alterações feitas. Esse 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 comando git commit seguido de uma mensagem do commit 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 transmitir uma confirmação usando os recursos de integração Git do VS Code. Lembre-se de continuar seu trabalho no mesmo computador. Se você trocar de computador, não terá a última versão do branch de trabalho para continuar.

1. Certifique-se de que o repositório local ainda tenha a mesmo branch de trabalho com check-out. Na interface do usuário do VS Code, o branch é mostrado no canto inferior esquerdo. O nome do branch também funciona como um botão para alternar branches.

   

2. Na barra lateral esquerda do VS Code, selecione a ferramenta de bifurcação para ver o painel de Controle do código-fonte: Git.

   

   O arquivo editado 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. Preparar as alterações. Passe o mouse sobre a linha Alterações até que um ícone + apareça. Selecione esse ícone. Essa ação é equivalente ao comando git add. O arquivo agora aparece na seção Alterações preparadas.

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

   

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

   

Você conseguiu! Seu código já está no repositório do GitHub e agora você pode abrir uma PR.

Precisa corrigir algo que já enviou? É fácil! Basta repetir as etapas acima, começando em Editar o arquivo, para fazer suas alterações no mesmo branch e, em seguida, confirmar e transmiti-las novamente (sem a necessidade de definir o servidor upstream em envios subsequentes do mesmo branch). Geralmente, os branches são usados para separar fluxos de trabalho. Portanto, você não precisa criar um branch, a menos que esteja pronto para trabalhar em outra coisa.

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

Pronto para fazer outra alteração, sem relação com esta? Volte ao branch padrão, transfira do repositório upstream para atualizar o garfo e faça o check-out de um novo branch. 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 um novo branch vinculado ao seu branch remoto e está pronto para fazer mais alterações. Você está no caminho certo para se tornar um contribuidor especialista!

Próximas etapas

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