Documentação do Git e do GitHub para o Microsoft Learn

  • Artigo

Descrição geral

Como colaborador da documentação do Microsoft Learn, você interagirá com várias ferramentas e processos. Vai trabalhar em paralelo com outros contribuidores no mesmo projeto, possivelmente no mesmo conteúdo e até ao mesmo tempo. Tudo isto é permitido pelo software do Git e do GitHub.

O Git é um sistema de controlo de versões de código aberto. Facilita este tipo de colaboração em projetos através de um controlo de versões distribuído de ficheiros que residem nos repositórios. Essencialmente, o Git torna possível integrar fluxos de trabalho realizados por vários contribuintes ao longo do tempo, para um determinado repositório.

O GitHub é um serviço de hospedagem baseado na Web para repositórios Git, como aqueles usados para armazenar conteúdo do Microsoft Learn . Em qualquer projeto, o GitHub aloja o repositório principal, do qual os contribuidores podem fazer cópias para trabalharem.

Este artigo define os principais termos que fazem parte do fluxo de trabalho do Microsoft Learn. Ele também fornece 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.

Filial

Os ramos separam os fluxos de trabalho (normalmente denominados versões). As contribuições são sempre realizadas no âmbito de um ramo específico.

Isolar alterações relacionadas a uma ramificação específica permite que você controle e introduza essas alterações de forma independente. Na realidade, dependendo do tipo de trabalho que realiza, pode facilmente ver-se com vários ramos de trabalho no seu repositório. Não é invulgar trabalhar com vários ramos em simultâneo, cada um a representar um projeto diferente.

Todos os repositórios contêm uma ramificação 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 à 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.

Sempre que você introduz um novo conjunto de alterações logicamente relacionadas, é uma prática recomendada criar uma ramificação de trabalho para gerenciar suas alterações. Não recomendamos fazer alterações diretamente na ramificação padrão.

Fork

Este termo é normalmente usado como um substantivo quando se refere a uma cópia de um repositório GitHub principal. Na prática, um fork é apenas outro repositório. Contudo, é especial, no sentido em que o GitHub mantém uma ligação com o repositório principal/primário. Este termo às vezes é usado como um verbo, como em "Você deve bifurcar o repositório primeiro."

Git

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

O Git também utiliza uma estrutura escalonada para armazenar e gerir conteúdos de um projeto:

  • Repositório: também denominado repo, é a maior unidade de armazenamento. Um repositório contém um ou mais ramos.
  • Ramo: uma unidade de armazenamento que contém os ficheiros e pastas que constituem o conjunto de conteúdos de um projeto. Para obter mais informações sobre ramificações, consulte a seção Ramificação deste artigo.

Os contribuidores interagem com o Git para atualizar e manipular os repositórios, tanto localmente como no GitHub:

  • Localmente através de ferramentas como a consola do Git Bash, que suporta comandos do Git para gerir repositórios locais e comunicar com os repositórios do GitHub.
  • Através do site www.github.com, que integra o Git para gerir a reconciliação de contribuições que regressam ao repositório principal.

GitHub

Nota

Embora a orientação da documentação seja baseada no uso do GitHub, algumas equipes usam o Visual Studio Team Services para hospedar repositórios Git. O cliente Visual Studio Team Explorer fornece uma GUI para a interação com repositórios do Team Services, como alternativa aos comandos do Git através de uma linha de comandos.
Além disso, muitas das diretrizes a seguir foram desenvolvidas como práticas recomendadas a partir de anos de experiência na hospedagem de conteúdo de serviço do Azure no GitHub. Eles podem ser necessários em alguns repositórios do Microsoft Learn.

Todos os fluxos de trabalho começam e terminam no nível do GitHub, onde o repositório principal de qualquer projeto de documentação é armazenado. As cópias que os contribuidores criam para sua própria utilização são distribuídas por vários computadores. Estas cópias acabam por ser novamente reconciliadas no repositório principal do GitHub do projeto.

Organização do diretório

A ramificação padrão de um projeto serve como a versão atual do conteúdo para o projeto. O conteúdo na ramificação padrão - e ramificações criadas a partir dela - é alinhado com a organização dos artigos nas páginas correspondentes do Microsoft Learn. Os subdiretórios são usados para separar artigos semelhantes (como serviços), conteúdo de mídia (como arquivos de imagem) e arquivos "include" (que permitem a reutilização de conteúdo).

Subdiretório Artigos

Normalmente, pode encontrar um articles diretório principal fora da raiz do repositório. O articles diretório contém um conjunto de subdiretórios Artigos nos subdiretórios são formatados como arquivos Markdown que usam uma extensão .md . Alguns repositórios que suportam vários serviços utilizam um subdiretório /articles genérico, como o repositório Azure-Docs. Outros poderão utilizar um nome específico do serviço, como o repositório IntuneDocs, que utiliza /IntuneDocs.

Na raiz deste diretório, pode encontrar artigos gerais relativos ao produto ou ao serviço geral. Por norma, poderá encontrar outra série de subdiretórios, que correspondem às funcionalidades/serviços ou a cenários comuns. Por exemplo, os artigos sobre as "máquinas virtuais" do Azure estão no subdiretório /virtual-machines e os artigos "compreender e explorar" do Intune estão no subdiretório /understand-explore.

Subdiretório de suporte de dados

Cada diretório de artigos contém um subdiretório /media para os ficheiros multimédia correspondentes. Os ficheiros multimédia contêm imagens utilizadas por artigos que têm imagens de referência.

Subdiretório de inclusões

Sempre que existir conteúdo reutilizável que seja partilhado por dois ou mais artigos, esse conteúdo é colocado num subdiretório /includes fora do diretório principal articles. Num ficheiro Markdown que utilize o ficheiro de inclusão, é colocada uma extensão Markdown "include" correspondente na localização onde o ficheiro de inclusão tem de ser referenciado.

Consulte Markdown reference: Includes para obter orientações adicionais.

Modelo de ficheiro em Markdown

Para conveniência, o diretório raiz de cada repositório contém normalmente um ficheiro de modelo Markdown denominado template.md. Pode utilizar esse ficheiro de modelo como o "ficheiro de iniciação" se precisar de criar um novo artigo para ser enviado para o repositório. O ficheiro contém:

  • Um cabeçalho com metadados no topo do ficheiro, delimitado por duas linhas de 3 hífenes. Contém as várias etiquetas utilizadas para monitorizar informações relacionadas com o artigo. Os metadados do artigo permitem determinadas funcionalidades, como a atribuição do autor, a atribuição do contribuidor, os endereços e as descrições de artigos. Também incluem otimizações do SEO e processos de relatório que a Microsoft utiliza para avaliar o desempenho do conteúdo. Por isso, os metadados são importantes!
  • Uma secção de metadados que descreve as várias etiquetas e valores dos metadados. Se tiver dúvidas quanto aos valores a utilizar na secção dos metadados, pode deixá-los em branco ou criar um comentário com uma hashtag (#) inicial e eles serão revistos/preenchidos pelo revisor do pedido Pull do repositório.
  • Vários exemplos da utilização do Markdown para formatar os elementos de um artigo.
  • Instruções gerais sobre a utilização de extensões Markdown, que pode utilizar para vários tipos de alertas.
  • Exemplos de incorporação de um vídeo através da utilização de um iFrame.
  • Instruções gerais sobre o uso de extensões de documentação técnica da Microsoft, que você pode usar 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 fluxo de trabalho do Microsoft Learn, a origem representa a conexão com a bifurcação. Esse termo às vezes é usado como um apelido para o repositório de origem em si, como em "Lembre-se de enviar suas alterações para a origem".

Pedidos Pull

Um pull request (PR) é um pedido 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 solicitando que as alterações (também conhecidas como commits) do seu ramo de trabalho sejam puxadas e mescladas em outro ramo. Na maioria dos casos, essa outra ramificação é a ramificação padrão no repositório principal.

Um PR também serve como um mecanismo para fornecer ao colaborador feedback dos processos de validação do Microsoft Learn e ao revisor de RP para resolver problemas ou dúvidas antes que as alterações sejam mescladas na ramificação padrão.

Remoto

Um remoto é uma conexão nomeada com um repositório remoto, como o controle remoto "origem" ou "upstream". O Git se refere a isso como um controle remoto porque é usado para fazer referência a um repositório hospedado em outro computador. No fluxo de trabalho do Microsoft Learn, um remoto é sempre um repositório GitHub.

A Montante

Como o controle remoto de origem, upstream é uma conexão nomeada para outro repositório. No fluxo de trabalho do Microsoft Learn, o upstream representa a conexão entre o repositório local e o repositório principal a partir do qual a bifurcação foi criada. Esse termo às vezes é usado como um apelido para o próprio repositório upstream, como em "Lembre-se de extrair as últimas alterações do upstream".

Mais informações

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

Recursos de controle de origem do Git

Recursos do GitHub

FAQs

O que é o Git?

O Git ajuda a acompanhar as alterações quando muitas pessoas trabalham em código de computador juntas. É como uma máquina do tempo para o 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 bagunçar o trabalho umas das outras. Também ajuda a corrigir erros facilmente.

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 diferentes versões ao mesmo tempo sem problemas.

O que são filiais 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?

Uma confirmação é como um ponto de salvamento. É uma maneira de registrar as alterações feitas. Cada confirmação tem um ID exclusivo 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 no código com outras pessoas. Também ajuda a manter o controle de quem mudou o quê.

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

O Git é a ferramenta para acompanhar as 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 todos podem ver. Mas para projetos privados (apenas você e sua equipe), você pode precisar pagar. Eles oferecem diferentes planos com recursos extras.

O que são solicitações pull no GitHub?

Solicitações pull são como pedir para colocar suas alterações no projeto principal. As pessoas podem rever e discutir as alterações antes de serem 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 de segurança extras, como autenticação de dois fatores, para maior segurança.