Conceitos básicos da contribuição com o Microsoft Learn
Existem alguns termos que você precisa conhecer que irão ajudar a entender e executar o processo de contribuição. Não é necessário saber tudo o que acontece nos bastidores, mas uma visão geral de como a contribuição funciona ajudará você a entender por que o processo funciona dessa maneira.
Conceitos básicos 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 a maior 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ários stakeholders com diferentes linhas do tempo e objetivos para seus projetos. Os softwares do Git e do GitHub permitem que você trabalhe em paralelo com outros colaboradores no mesmo projeto, possivelmente com o mesmo conteúdo e até mesmo simultaneamente, sem interferir no trabalho de outras pessoas inadvertidamente.
O conteúdo é armazenado em arquivos em repositórios do Git (repos) hospedados no GitHub. Um repositório é uma unidade de armazenamento que contém os arquivos de um projeto e o histórico de revisão dos arquivos. Os repositórios podem ser públicos ou privados, e o Microsoft Learn é composto por uma combinação de ambos. Qualquer pessoa pode contribuir para um repositório público após configurar uma conta no GitHub. Repositórios privados só estão disponíveis para colaboradores que são funcionários da Microsoft ou que receberam uma permissão especial.
Editar conteúdo do Microsoft Learn armazenado em um repositório do GitHub
Para qualquer projeto, o GitHub hospeda o repositório principal e qualquer fork. Um fork é uma cópia do repositório principal que um colaborador faz para seu próprio trabalho. Um fork é uma das formas que o GitHub tem de proteger o conteúdo publicado. Em vez de editar diretamente o conteúdo no branch do repositório principal publicado ativo, o GitHub tira um instantâneo desse conteúdo para o seu fork, onde você poderá fazer suas alterações.
Os repositórios do GitHub contêm um ou mais branches. Um branch é 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 um fork, contêm um branch padrão (geralmente chamado de "main") e um ou mais branches destinados a serem mesclados novamente com o branch padrão. A ramificação padrão funciona como a versão atual e "única fonte de verdade" para o projeto. Ele é o pai e todos os outros branches no repositório são criados dele.
Aparentemente, a edição de um artigo de documentação em um repositório público começa com o toque de um botão, mas há várias coisas acontecendo nos bastidores. Ao iniciar o processo de edição baseado em navegador, um fork do repositório é criado (se você ainda não tiver um) e usado para as suas alterações. Você edita dentro de um branch da sua bifurcação que, posteriormente, será mesclado com o branch ativo do repositório principal para que suas alterações fiquem disponíveis para todos.
Crie uma solicitação de pull
Como essa mesclagem é feita? Você precisa informar ao GitHub, especificamente, aos proprietários do repositório principal e autores do artigo, que suas edições estão finalizadas e prontas para revisão, publicação e para o mundo inteiro ver! Para isso, você deve criar e enviar um pull request.
Um PR (pull request) é uma proposta para que suas alterações, feitas no branch no fork em que você estava trabalhando, sejam mescladas com o branch padrão "main" do repositório ativo. Ao trabalhar em um repositório público, seus pull requests sempre serão revisados por um revisor humano antes de serem mescladas. Também poderão ser feitas algumas verificações automatizadas, como, por exemplo, relacionadas à compatibilidade de mesclagem e à validação do build. Após essas revisões serem concluídas e todos os problemas resolvidos, suas alterações serão mescladas ao branch ativo e ficarão disponíveis no Microsoft Learn!
Fluxo de trabalho para pequenas contribuições na documentação
Em resumo, siga essas etapas gerais ao fazer pequenas alterações na documentação da Microsoft usando o editor Web no GitHub:
- Ao abrir um arquivo no navegador para editar, um fork do repositório público é criado automaticamente para você. Também é criado um branch no seu fork, muitas vezes chamado de branch de patch.
- Faça suas alterações no arquivo.
- Crie um pull request para propor que suas alterações sejam revisadas e mescladas.
- Seu PR deve resolver qualquer problema e ser aprovado em todas as revisões.
- Seu PR é mesclado com o branch principal do repositório ativo e suas alterações são publicadas no Microsoft Learn.
Em seguida, examinaremos cada etapa mais de perto para saber como executá-las.