Fundamentos de contribuição para o Microsoft Learn
Existem alguns termos a conhecer que o ajudarão a compreender e concluir o processo de contribuição. Não é necessário saber tudo o que acontece sob o capô, mas uma visão geral de como a contribuição funciona ajuda você a entender por que o processo funciona da maneira que funciona.
Fundamentos do Microsoft Learn e do GitHub
O Microsoft Learn contém milhares de artigos, módulos de treinamento, páginas da Web e muito mais, que precisam ser armazenados e acessados regularmente por vários colaboradores. O Microsoft Learn usa o GitHub para armazenar grande parte desse conteúdo. O GitHub é uma plataforma que usa o Git, um sistema de controle de versão distribuído, para armazenar projetos e facilitar a colaboração entre várias partes interessadas com diferentes objetivos e cronogramas do projeto. O software Git e GitHub permite que você trabalhe em paralelo com outros colaboradores no mesmo projeto, potencialmente o mesmo conteúdo, mesmo ao mesmo tempo, sem interferir involuntariamente no trabalho de outras pessoas.
O conteúdo é armazenado em arquivos em repositórios Git (repositórios ) hospedados no GitHub. Um repositório é uma unidade de armazenamento que contém os arquivos e o histórico de revisão de arquivos de um projeto. Os repositórios podem ser públicos ou privados, e o Microsoft Learn é composto por uma mistura de ambos. Qualquer pessoa pode contribuir para um repositório público depois de configurar uma conta do GitHub. Os repositórios privados só estão disponíveis para colaboradores que sejam funcionários da Microsoft ou que tenham recebido permissão especial.
Fazer edições no conteúdo do Microsoft Learn armazenado em um repositório GitHub
Para qualquer projeto, o GitHub hospeda o repositório principal e quaisquer bifurcações. Um fork é uma cópia do repositório principal que um colaborador faz para o seu próprio trabalho. Uma bifurcação é uma das formas do GitHub de proteger o conteúdo publicado. Em vez de editar diretamente o conteúdo na ramificação ao vivo e publicada do repositório principal, o GitHub tira um instantâneo desse conteúdo para sua bifurcação para que você possa fazer suas alterações lá.
Os repositórios do GitHub contêm uma ou mais ramificações. Uma ramificação é uma unidade de armazenamento que contém os arquivos e pastas que compõem o conjunto de conteúdo de um projeto. Todos os repositórios, seja o repositório principal ou uma bifurcação, contêm uma ramificação padrão (normalmente chamada principal) e uma ou mais ramificações destinadas a serem mescladas novamente na ramificação padrão. A ramificação padrão serve como a versão atual e "única fonte de verdade" para o projeto. É o elemento principal a partir do qual todos os outros ramos do repositório são criados.
Editar um artigo de documentação em um repositório público pode parecer que começa com o toque de um botão, mas há várias coisas acontecendo nos bastidores. Quando você inicia o processo de edição baseado em navegador, uma bifurcação do repositório é criada (se você ainda não tiver uma) e usada para suas alterações. Você edita dentro de uma ramificação da sua bifurcação, que mais tarde será mesclada à ramificação ativa do repositório principal para que suas alterações estejam disponíveis para todos.
Criar um pedido Pull
Como acontece essa fusão? Você precisa dizer ao GitHub — especificamente, os proprietários do repositório principal e os autores do artigo — que suas edições estão finalizadas e prontas para revisão, publicação e o mundo para ver! Para fazer isso, você cria e envia uma solicitação pull.
Uma solicitação pull (PR) é uma proposta para que suas alterações sejam mescladas da ramificação em sua bifurcação em que você estava trabalhando para a ramificação principal padrão do repositório ativo. Quando você trabalha em um repositório público, suas solicitações pull são sempre revisadas por um revisor humano antes de serem mescladas. Também pode haver algumas verificações automatizadas, como compatibilidade de mesclagem e validação de compilação. Depois que essas revisões forem concluídas e quaisquer problemas resolvidos, suas alterações serão mescladas à ramificação ativa e ficarão disponíveis no Microsoft Learn!
Fluxo de trabalho para contribuições menores para a documentação
Em resumo, você seguirá estas etapas gerais ao fazer pequenas alterações na documentação da Microsoft usando o editor da Web no GitHub:
- Quando você abre um arquivo em seu navegador para editar, uma bifurcação do repositório público é criada automaticamente para você. Uma ramificação na sua bifurcação também é criada, muitas vezes chamada de ramificação de patch.
- Faça as alterações no arquivo.
- Crie uma solicitação pull para propor que suas alterações sejam revisadas e mescladas.
- Seu RP deve resolver quaisquer problemas e passar em todas as avaliações.
- Seu PR é mesclado à ramificação principal do repositório ativo e suas alterações são publicadas no Microsoft Learn.
A seguir, vamos analisar cada passo mais de perto para aprender como realizá-los.