Conceitos básicos do Git e do GitHub para a documentação do Microsoft Learn

  • Artigo

Visão geral

Como colaborador da documentação do Microsoft Learn, você irá interagir com diversas ferramentas e processos. Você trabalhará em paralelo com outros contribuidores no mesmo projeto, possivelmente com o mesmo conteúdo exato e até mesmo simultaneamente. Isso tudo é possibilitado por meio do Git e do software GitHub.

O Git é um sistema de controle de versão de código-fonte aberto. Ele facilita esse tipo de colaboração no projeto por meio do controle de versão distribuído de arquivos que residem em repositórios. Em essência, o Git possibilita a integração de fluxos de trabalho realizados por vários contribuidores com o passar do tempo, para um determinado repositório.

O GitHub é um serviço de hospedagem na Web para repositórios do Git, como os usados para armazenar o conteúdo do Microsoft Learn. Para qualquer projeto, o GitHub hospeda o repositório principal, do qual os contribuidores podem fazer cópias para seus próprios trabalhos.

Este artigo define os principais termos que fazem parte do workflow do Microsoft Learn. Ele também apresenta uma visão geral dos repositórios Git e GitHub e explica como o conteúdo é organizado para a documentação técnica da Microsoft.

Branch

Os branches separam fluxos de trabalho (normalmente conhecidos como versões). As contribuições sempre são feitas para um branch específico e estão no escopo do mesmo.

O isolamento de alterações relacionadas em um branch específico permite que você controle e introduza essas alterações de forma independente. Na realidade, dependendo do tipo de trabalho que você faz, é possível que você acabe criando vários branches de trabalho no repositório. Não é incomum trabalhar em vários branches simultaneamente, cada um representando um projeto diferente.

Todos os repositórios contêm uma branch padrão (normalmente chamada de "Principal") e uma ou mais ramificações de trabalho em andamento (que chamamos de Ramificações de trabalho) que ainda não foram integradas à branch padrão. O branch padrão funciona como a versão atual e "fonte única de verdade" para o projeto. Ele é o pai e todos os outros branches no repositório são criados dele.

Sempre que você introduz um novo conjunto de alterações relacionadas logicamente, a melhor prática é criar um branch de trabalho para gerenciar as alterações. Não recomendamos alterar diretamente na branch padrão.

Fork

Normalmente, este termo é usado como um substantivo ao referir-se a uma cópia de um repositório principal do GitHub. Na prática, um fork é só outro repositório. Mas é especial, no fato de que o GitHub mantém uma conexão com o repositório principal/pai. Às vezes, este termo é usado como verbo, como "Primeiro, você precisa fazer um fork do repositório".

Git

Se estiver familiarizado com sistemas de controle de versão centralizados (como Team Foundation Server, SharePoint ou Visual SourceSafe), você verá que o Git tem um fluxo de trabalho de contribuição e uma terminologia exclusivos para dar suporte ao modelo distribuído. Por exemplo, normalmente, não há um bloqueio de arquivo associado a operações de check-out/check-in. Em vez disso, o Git se preocupa com alterações em um nível ainda maior, comparando arquivos byte por byte.

O Git também usa uma estrutura em camadas para armazenar e gerenciar o conteúdo de um projeto:

  • Repositório: também conhecido como repo, é a maior unidade de armazenamento. Um repositório contém um ou mais branches.
  • Branch: uma unidade de armazenamento que contém os arquivos e as pastas que compõem o conjunto de conteúdo de um projeto. Para saber mais sobre ramificações, consulte a seção Branch deste artigo.

Os contribuidores interagem com o Git para atualizar e manipular repositórios nos níveis local e do GitHub:

  • Localmente, por meio de ferramentas como o console Git Bash, que dá suporte a comandos do Git para gerenciamento de repositórios locais e comunicação com os repositórios do GitHub.
  • Por meio do www.github.com, que integra o Git para gerenciar a reconciliação de contribuições que retornam ao repositório principal.

GitHub

Observação

Embora as diretrizes de documentação sejam baseadas no uso do GitHub, algumas equipes usam o Visual Studio Team Services para hospedar repositórios do Git. O cliente Team Explorer para Visual Studio fornece uma GUI para interagir com os repositórios do Team Services, que é uma alternativa ao uso de comandos do Git por meio de uma linha de comando.
Além disso, muitas das diretrizes a seguir foram desenvolvidas como práticas recomendadas após anos de experiência em hospedagem de conteúdo do serviço do Azure no GitHub. Elas podem ser necessárias em alguns repositórios do Microsoft Learn.

Todos os fluxos de trabalho começam e terminam no nível do GitHub, no qual o repositório principal de qualquer projeto de documentação é armazenado. As cópias que os contribuidores criam para uso próprio são distribuídas entre vários computadores. Essas cópias são eventualmente reconciliadas novamente no repositório principal do projeto no GitHub.

Organização de diretório

Um branch padrão de um projeto funciona como a versão atual do conteúdo do projeto. O conteúdo no branch padrão - e dos branches criados a partir dele - é alinhado sem muita rigidez com a organização dos artigos nas páginas correspondentes do Microsoft Learn. Os subdiretórios são usados para separar de artigos parecidos (como serviços), conteúdo de mídia (como arquivos de imagem) e arquivos de "inclusão", que permitem a reutilização de conteúdo.

Subdiretório de artigos

Normalmente, é possível encontrar um diretório articles principal fora da raiz do repositório. O diretório articles contém um conjunto de subdiretórios Artigos nos subdiretórios que são formatados como arquivos Markdown que usam uma extensão .md. Alguns repositórios com suporte a vários serviços usam um subdiretório /articles genérico, como o repositório Azure-Docs. Outros podem usar um nome específico do serviço, assim como o repositório IntuneDocs, que usa /IntuneDocs.

Na raiz deste diretório, você pode encontrar artigos gerais relacionados ao serviço ou produto geral. E, normalmente, é possível encontrar outra série de subdiretórios que correspondem aos recursos/serviços ou cenários comuns. Por exemplo, os artigos sobre "máquina virtual" do Azure estão no subdiretório /virtual-machines e os artigos sobre "entender e explorar" do Intune estão no subdiretório /understand-explore.

Subdiretório de mídia

Cada diretório de artigo contém um subdiretório /media para os arquivos de mídia correspondentes. Os arquivos de mídia contêm as imagens usadas pelos artigos que têm referências de imagem.

Inclui subdiretório

Sempre que houver conteúdo reutilizável compartilhado entre dois ou mais artigos, ele será colocado em um subdiretório /includes fora do diretório articles principal. Em um arquivo Markdown que use o arquivo de inclusão, uma extensão de Markdown "include" correspondente será colocada no local em que o arquivo de inclusão deve ser referenciado.

Confira Referência do Markdown: inclusões para obter diretrizes adicionais.

Modelo de arquivo Markdown

Para sua conveniência, o diretório raiz de cada repositório normalmente contém um arquivo de modelo de Markdown chamado template.md. Você poderá usar esse arquivo de modelo como um “arquivo inicial” se precisar criar um novo artigo para ser enviado ao repositório. O arquivo contém:

  • O cabeçalho de metadados na parte superior do arquivo, delimitado por duas linhas de três hifens. Ele contém as várias tags usadas para rastrear informações relacionadas ao artigo. Os metadados do artigo habilitam algumas funcionalidades, como atribuição de autor, atribuição de contribuidor, trilhas e descrições do artigo. Ele também inclui otimizações de SEO e processos de relatórios que a Microsoft usa para avaliar o desempenho do conteúdo. Portanto, os metadados são importantes!
  • A seção de metadados que descreve as várias tags e valores de metadados. Se não tiver certeza dos valores a serem usados para a seção de metadados, deixe-os em branco ou comente com uma hashtag à esquerda (#), e eles serão revisados/preenchidos pelo revisor da pull request do repositório.
  • Vários exemplos de uso de Markdown para formatar os elementos de um artigo.
  • Instruções gerais sobre o uso de extensões de Markdown, que podem ser usadas para vários tipos de alertas.
  • Exemplos de incorporação de vídeo usando um iframe.
  • Instruções gerais sobre o uso de extensões de documentação técnica da Microsoft, que podem ser usadas para controles especiais, como botões e seletores.

Origem

Este termo é o nome atribuído à conexão entre o repositório local e o repositório do qual ele foi clonado. No workflow do Microsoft Learn, a origem representa a conexão com o garfo. Às vezes, este termo é usado como um moniker para o próprio repositório origin, como em "Lembre-se de enviar suas alterações por push para a origem".

Solicitações pull

Uma pull request (PR) é uma solicitação para que um proprietário de conteúdo puxe suas alterações para a fonte oficial. Um PR habilita o modelo de colaboração do GitHub ao solicitar as alterações (também conhecidas como commits) da sua ramificação de trabalho seja realizado e que elas sejam mescladas com outra ramificação. Na maioria dos casos, esse outro branch é o branch padrão no repositório principal.

Uma PR também serve como um mecanismo para fornecer ao colaborador comentários de processos de validação do Microsoft Learn, do revisor da PR, a fim de resolver problemas ou perguntas antes de mesclar as alterações no branch padrão.

Remoto

Um remote é uma conexão nomeada com um repositório remoto, como o remoto de "origin" ou "upstream". O Git se refere a ele como remoto porque ele é usado para referenciar um repositório hospedado em outro computador. Nesse workflow do Microsoft Learn, um remote é sempre um repositório do GitHub.

Upstream

Assim como o remote origin, upstream é uma conexão nomeada com outro repositório. Neste fluxo de trabalho do Microsoft Learn, upstream representa a conexão entre seu repositório local e o repositório principal, a partir do qual seu fork foi criado. Às vezes, este termo é usado como um moniker para o próprio repositório upstream, como em "Lembre-se de enviar suas mais recentes alterações por push do upstream".

Saiba mais

Caso você não esteja familiarizado com o Git ou o GitHub, esses recursos podem ajudá-lo a aprender, ser produtivo ou responder a perguntas.

Recursos de controle do código-fonte do Git

Recursos do GitHub

Perguntas Frequentes

O que é o Git?

O Git ajuda a acompanhar as alterações quando muitas pessoas trabalham juntas em código de computador. É como uma máquina do tempo para código, para que você possa ver o que mudou e voltar se necessário.

Por que usar o Git?

É ótimo para o trabalho em equipe. O Git torna mais fácil para muitas pessoas trabalharem no mesmo projeto sem atrapalhar o trabalho um do outro. Também ajuda a corrigir erros com facilidade.

Como funciona o Git?

O Git armazena todas as versões do código de um projeto. Quando você faz alterações, o Git tira uma foto (como um instantâneo) do que é diferente. Você pode fazer versões diferentes ao mesmo tempo sem problemas.

O que são ramificações no Git?

As ramificações são como caminhos diferentes em um projeto. Eles permitem que as pessoas trabalhem em coisas novas sem alterar o projeto principal. Mais tarde, eles podem trazer essas mudanças de volta para o projeto principal.

O que é um commit no Git?

Um commit é como um ponto de salvamento. É uma maneira de registrar as alterações que você fez. Cada commit tem uma ID exclusiva e uma nota sobre o que foi alterado.

O que é o GitHub?

O GitHub é um site onde você pode armazenar seus projetos Git. É como um grande hub para compartilhar e trabalhar em conjunto em código com outras pessoas. Ele também ajuda a acompanhar quem mudou o quê.

Qual é a diferença entre o GitHub e o Git?

O Git é a ferramenta para rastrear alterações, enquanto o GitHub é o lugar para armazenar seus projetos e trabalhar juntos. O GitHub usa o Git para fazer sua mágica.

O GitHub é gratuito?

Sim, para projetos que todos podem ver. Mas para projetos privados (apenas você e sua equipe), pode ser necessário pagar. Eles oferecem diferentes planos com recursos extras.

O que são pull requests no GitHub?

Pull requests são como pedidos para colocar suas alterações no projeto principal. As pessoas podem revisar e discutir as alterações antes que elas sejam adicionadas.

Quão seguro é o GitHub?

O GitHub cuida bem da segurança. Eles usam códigos e regras especiais para garantir que apenas as pessoas certas possam acessar e alterar seu código. Você também pode adicionar camadas extras de segurança, como autenticação de dois fatores, para obter mais segurança.