Visão geral do guia de contribuidor do Microsoft Learn

  • Artigo

Bem-vindo ao guia de contribuidor do Microsoft Learn!

Compartilhar sua experiência com outras pessoas no Microsoft Learn ajuda todos a alcançar mais. Use as informações neste guia para publicar um novo artigo no Microsoft Learn ou fazer atualizações em um artigo publicado existente.

Vários dos conjuntos de documentação da Microsoft são de software livre e estão hospedados no GitHub. Nem todos os conjuntos de documentos são completamente código aberto, mas muitos têm repositórios voltados para o público onde você pode sugerir alterações por meio de PRs (pull requests). Essa abordagem de software livre otimiza e aprimora a comunicação entre os engenheiros de produto, as equipes de conteúdo e os clientes, além de apresentar outras vantagens:

  • planejamento no aberto para obter comentários sobre quais documentos e aprimoramentos são mais necessários
  • revisão em aberto para obter uma avaliação útil da comunidade de materiais
  • atualizando em aberto para facilitar a melhoria contínua do conteúdo

Comece a contribuir editando um documento que você está exibindo. Ou então, colabore analisando novos tópicos ou criando registros de problemas de qualidade.

Importante

Todos os repositórios publicados no Microsoft Learn adotaram o Código de Conduta do Microsoft Open Source ou o Código de Conduta do .NET Foundation. Para obter mais informações, consulte Perguntas frequentes sobre código de conduta. Entre em contato com opencode@microsoft.com ou conduct@dotnetfoundation.org com perguntas ou comentários.

Correções secundárias ou esclarecimentos sobre documentação e exemplos de código em repositórios públicos são abordados pelos Termos de Uso do learn.microsoft.com. Quando há alterações novas ou significativas, é gerado um comentário na PR, pedindo que você envie um CLA (Contrato de Licença de Contribuição) online caso não seja um funcionário da Microsoft. Para analisarmos ou aceitarmos sua PR, primeiro preencha o formulário online.

Edições rápidas na documentação

Com as edições rápidas, ficou mais fácil relatar e corrigir pequenos erros e omissões na documentação. Apesar de todos os esforços, pequenos erros gramaticais e ortográficos aparecem em nossos documentos publicados. Embora você possa criar registros de problemas para relatar erros, é mais fácil e rápido criar uma PR para corrigir o problema, quando a opção estiver disponível.

  1. Você precisa de uma conta do GitHub para contribuir. Se você já tiver uma conta, verifique se está conectado. Se você não tiver uma conta do GitHub, navegue até https://github.com/join para um processo de inscrição rápido e gratuito.

  2. Navegue até a documentação que você deseja editar. Algumas páginas de documentos permitem a edição do conteúdo diretamente no navegador. Nesse caso, você verá um ícone Editar lápis como o mostrado abaixo. Escolher o ícone Editar lápis leva você para o arquivo de origem no GitHub.

    Captura de tela de um artigo de documentação do Azure mostrando o ícone editar lápis.

    Se o botão Editar não for exibido, isso significará que o conteúdo não está aberto para contribuições públicas. Algumas páginas são geradas (por exemplo, por meio da documentação embutida no código) e precisam ser editadas no projeto a que pertencem.

  3. Selecione o ícone de lápis na parte superior da página de arquivo do GitHub. Se o ícone de lápis estiver esmaecido ou não for exibido, você precisará fazer logon em sua conta do GitHub.

    Captura de tela do artigo do Azure no GitHub mostrando o ícone de lápis de edição.

    Na parte superior do artigo estão os metadados do artigo. Os metadados são aplicados a artigos para relatórios, capacidade de descoberta por meio de pesquisa e aspectos de condução da experiência do site. Se você estiver fazendo pequenas atualizações em um artigo publicado, provavelmente não precisará alterar os metadados.

  4. Se for sua primeira vez trabalhando neste repositório, você será solicitado a bifurcar o repositório antes de propor alterações. Selecione Bifurcar este repositório para continuar.

  5. Edite o arquivo no editor da Web. Escolha a guia Visualização na barra de ferramentas para marcar a formatação das alterações.

  6. Quando terminar de editar, selecione o botão Confirmar alterações ou Propor alterações , geralmente no canto superior direito da tela.

  7. Insira um mensagem do commit. O mensagem do commit se torna o título de sua PR e deve ser um breve resumo de suas alterações (por exemplo, "Corrigir erros ortográficos e gramaticais"). Opcionalmente, adicione uma descrição estendida para fornecer mais detalhes sobre suas alterações. Selecione Propor alterações:

    Captura de tela do pop-up propor alterações.

  8. Agora que você propôs e confirmou suas alterações, solicite aos proprietários do repositório que eles "efetuem pull" dessas alterações no repositório. Isso é feito usando uma PR ( solicitação de pull). Ao selecionar Propor alterações, você verá uma página como esta:

    Captura de tela da tela comparando alterações.

    Selecione comparar entre bifurcações e verifique se a configuração do branch é semelhante à mostrada acima. Sua PR deve propor alterações de seu fork e branch (representados pelos dois itens no lado direito da seta) para o fork e main branch do repositório MicrosoftDocs (representados pelos dois itens no lado esquerdo da seta). Talvez seja necessário selecionar as caixas suspensas para ajustar os nomes de repositório e branch.

    Examine as alterações e selecione Criar solicitação de pull.

  9. Na página Abrir uma solicitação de pull , visualize sua PR. Você pode alterar os campos de título ou descrição, se necessário. Quando estiver pronto, selecione Criar solicitação de pull. Essa ação abre sua PR.

  10. Se tudo estiver bem e você terminar de editar, adicione um comentário que leia #sign-off. Isso alerta a equipe de revisão de PR de que sua PR está pronta para ser revisada.

    Captura de tela da caixa de comentários do GitHub em uma PR com um comentário lendo #sign-off.

  11. É isso! Membros da equipe de conteúdo analisarão e mesclarão sua PR quando for aprovada. Você poderá receber um feedback solicitando alterações.

A interface do usuário de edição do GitHub responde às suas permissões no repositório. As imagens anteriores são exibidas para os colaboradores que não têm permissões de gravação no repositório de destino. O GitHub cria automaticamente um fork para o repositório de destino em sua conta. O nome de fork recém-criado tem o formato GitHubUsername/RepositoryName por padrão. Se você tiver acesso de gravação ao repositório de destino, como seu fork, o GitHub criará um branch nele. O nome do branch tem o formato padrão patch-n e usa um identificador numérico para o branch do patch.

Usamos solicitações de pull para todas as alterações, até mesmo para colaboradores que têm acesso de gravação. A maioria dos repositórios protege o branch padrão para que as atualizações sejam enviadas como PRs.

A experiência de edição no navegador é a melhor para alterações secundárias ou esporádicas. Se fizer grandes colaborações ou usar recursos avançados do Git (como gerenciamento de branch ou resolução avançada de conflitos de mesclagem), você precisará criar um fork do repositório e trabalhar localmente.

Observação

A maioria das documentações localizadas não oferece a capacidade de editar ou fornecer comentários por meio do GitHub. Para fornecer comentários sobre conteúdo localizado, use https://aka.ms/provide-feedback o formulário.

Examinar PRs abertas no GitHub

Você pode ler novos tópicos antes que eles sejam publicados verificando a fila de RP aberta no GitHub. As revisões seguem o processo do fluxo do GitHub. Você pode ver as atualizações propostas ou novos artigos em repositórios públicos. Revise-os e adicione seus comentários. Examine qualquer um dos nossos repositórios do Microsoft Learn e marcar as PRs abertas para áreas que lhe interessam. Os comentários da comunidade sobre atualizações propostas ajudam toda a comunidade.

Criar problemas do GitHub

Nossos documentos estão sempre em evolução. Bons problemas do GitHub nos ajudam a concentrar nossos esforços nas prioridades mais altas para a comunidade. Quanto mais detalhes você fornecer, mais útil será o registro do problema. Diga-nos quais informações você buscou. Diga-nos quais termos de pesquisa você usou. Se você não souber como começar, diga-nos como deseja explorar novas tecnologias.

Muitas das páginas de documentação da Microsoft têm uma seção Comentários na parte inferior da página em que você pode optar por deixar comentários sobre o produto (Este link do produto) ou comentários de conteúdo (link desta página ) para acompanhar problemas específicos a esse artigo. Essas duas opções exigem que você faça logon no GitHub ou em algum outro sistema. Para deixar comentários anônimos, use o ícone De comentários que aparece no canto superior direito de cada artigo, abaixo do título.

Os registros de problemas é o pontapé inicial. A equipe de conteúdo responderá a esses problemas com ideias sobre o que podemos adicionar e pedir suas opiniões. Quando criarmos um rascunho, pediremos a você que revise a solicitação de pull.

Aumente seu engajamento

Outros tópicos neste guia ajudam você a começar a contribuir de forma produtiva para o Microsoft Learn. Eles explicam como trabalhar com repositórios do GitHub, ferramentas markdown e extensões usadas no conteúdo do Microsoft Learn.