Documentação de controle de versão

Em GitHub Docs, fornecemos versões de nossa documentação que refletem as diferenças na interface do usuário e na funcionalidade das ofertas de produtos principais de GitHub. Os colaboradores podem usar a sintaxe de controle de versão para definir o escopo do conteúdo para uma oferta de produto específica.

A sintaxe de controle de versão permite que o leitor escolha manualmente a versão da documentação que se aplica ao produto que está usando. As URLs do GitHub Docs também podem incluir informações de controle de versão, que permitem que os links de uma versão do GitHub Docs para outra enviem o leitor diretamente para a documentação do produto que ele está usando.

Como e onde fazer a versão

O controle de versão do conteúdo em GitHub Docs é de origem única para evitar repetição e manter a prosa DRY. Para artigos, você aplica o controle de versão ao arquivo Markdown individual com metadados YAML e usa instruções condicionais dentro da prosa do arquivo para instruir o site qual texto exibir dependendo da versão selecionada pelo leitor. A origem única contrasta com a criação de arquivos separados que refletem cada versão do conteúdo.

Há dois tipos de sintaxe de controle de versão de GitHub Docs.

• YAML: usado com mais frequência no front matter YAML em arquivos Markdown no content/, mas também em muitos tipos de arquivos YAML em data/. Indica o controle de versão de um conteúdo inteiro.

  versions:
    PRODUCT: 'VERSIONS'
    PRODUCT: 'VERSIONS'
    ...
  

  O exemplo a seguir mostra o conteúdo com controle de versão para as versões Free, Pro e Team e todas as versões do GitHub Enterprise Server.

  versions:
    fpt: *
    ghes: *
  

• Liquid: usado em arquivos Markdown em content/ e data/reusables/, cadeias de caracteres variáveis dentro de arquivos YAML em data/variables/ ou cadeias de caracteres dentro de data/glossaries/external.yml. Indica qual texto deve aparecer quando um leitor escolhe uma versão do conteúdo que tem várias versões definidas pelo front matter YAML.

  • Controle de versão baseado em produto:

    {% ifversion SHORT-PRODUCT-NAME %} ... {% endif %}
    

  • Controle de versão baseado em funcionalidade:

    {% ifversion FEATURE-NAME %} ... {% endif %}
    

Sobre as diferentes versões do GitHub

Fornecemos documentação com controle de versão para usuários de planos do GitHub, incluindo GitHub Enterprise Cloud e GitHub Enterprise Server. Se houver várias versões de uma página no site, os leitores poderão escolher a versão no seletor de versão na parte superior da página.

GitHub.com

A documentação do GitHub.com tem duas versões possíveis:

Planos Gratuito, Pro ou de Equipe

Para planos Gratuito, Pro ou de Equipe em GitHub.com, use free-pro-team@latest. O nome curto é fpt.

GitHub Enterprise Cloud

Para GitHub Enterprise Cloud, use enterprise-cloud@latest. O nome curto é ghec.

GitHub Enterprise Server

A documentação do GitHub Enterprise Server tem várias versões e pode ser dividida em dois tipos: documentação para versões com suporte (damos suporte a quatro ao mesmo tempo) e documentação para versões encerrando (não temos links para elas no site Docs, mas damos suporte a um instantâneo "congelado" desses documentos em perpetuidade, para que ainda possam ser acessados se você souber as URLs). Confira lib/enterprise-server-releases.js para obter uma lista.

As versões são chamadas de enterprise-server@<release>. O nome curto é ghes. Em condicionais Liquid, podemos especificar intervalos, como ghes > 3.0. Para obter mais informações, confira Controle de versão com operadores condicionais Liquid.

Controle de versão no frontmatter YAML

Você pode usar a propriedade versions no frontmatter do arquivo para definir para quais produtos um artigo será exibido. Os arquivos de índice exigem uma propriedade versions, mas serão automaticamente versionados com base nas versões de seus filhos.

Por exemplo, o frontmatter YAML a seguir fará a versão de um artigo para o GitHub Enterprise Server 2.20 e superiores, no plano Gratuito, Pro ou de Equipe.

title: About your personal dashboard
versions:
  fpt: '*'
  ghes: '>=2.20'

O exemplo a seguir fará a versão de um artigo para todas as versões com suporte do GitHub Enterprise Server:

title: Downloading your license
versions:
  ghes: '*'

Você também pode controlar uma versão de uma página para um intervalo de versões. O exemplo a seguir criará a versão da página para as versões Free, Pro e Team, o GitHub Enterprise Cloud e o GitHub Enterprise Server versões 3.1 e 3.2 somente:

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>=3.1 <3.3'

Controle de versão com operadores condicionais Liquid

Usamos a linguagem do modelo Liquid (especificamente, esta porta Node.js) e uma marca personalizada {% ifversion ... %} para criar versões da nossa documentação.

Se você definir vários produtos na chave versions dentro do frontmatter YAML de uma página, poderá usar os operadores condicionais ifversion/else (ou ifversion/elsif/else) no Markdown para controlar como o site renderiza o conteúdo na página para um produto específico. Por exemplo, um recurso pode ter mais opções em GitHub.com do que em GitHub Enterprise Server, para que você possa criar a versão do conteúdo adequadamente por meio das versions do frontmatter e usar condicionais Liquid para descrever as opções adicionais para GitHub.com.

Operadores de comparação

Para versões que não têm versões numeradas (como fpt e ghec), você tem duas opções:

• {% ifversion ghec %}
• {% ifversion not ghec %}

Para versões que têm versões numeradas (atualmente apenas ghes), você pode fazer o mesmo para o conteúdo que está disponível em todas as versões ou não está disponível em nenhuma das versões:

• {% ifversion ghes %}
• {% ifversion not ghes %}

Se você precisar denotar conteúdo disponível apenas (ou não disponível) em determinadas versões, poderá usar os seguintes operadores:

Operador	Significado	Exemplo
=	Igual a	{% ifversion ghes = 3.0 %}
>	Mais recente que	{% ifversion ghes > 3.0 %}
<	Com mais de	{% ifversion ghes < 3.0 %}
!=	Não igual a	{% ifversion ghes != 3.0 %} (não use not em intervalos)

Os operadores Liquid ==, >= e <= não têm suporte no GitHub Docs.

Operadores lógicos

Quando todos os operandos precisarem ser verdadeiros para que a condição seja verdadeira, use o operador and:

{% ifversion ghes > 2.21 and ghes < 3.1 %}

Quando pelo menos um operando precisar ser verdadeiro para que a condição seja verdadeira, use o operador or:

{% ifversion fpt or ghes > 2.21 %}

Não use os operadores && ou ||. O Liquid não os reconhece e o conteúdo não será renderizado nas versões pretendidas.

Controle de espaços em branco

Ao usar condicionais Liquid em listas, você pode usar os caracteres de controle de espaço em branco para impedir a adição de novas linhas ou espaços em branco que interromperão a renderização da lista.

Basta adicionar um hífen (-) à esquerda, à direita ou a ambos os lados para indicar que não deve haver uma nova linha ou outro espaço em branco naquele lado.

{%- ifversion fpt %}

Por exemplo, para fazer a versão de uma etapa de um procedimento, em vez de adicionar um controle de versão liquid para a linha que começa no final da linha anterior, da seguinte forma:

1. This step is for all versions{% ifversion ghes %}
1. This step is for GHES only{% endif %}
1. This step is for all versions

Você pode incluir o controle de versão liquid em sua própria linha e usar o controle de espaço em branco para distribuir a nova linha à esquerda da tag liquid. Isso torna a leitura da fonte muito mais fácil, sem quebrar a renderização da lista:

1. This step is for all versions
{%- ifversion ghes %}
1. This step is for GHES only
{%- endif %}
1. This row is for all versions

Sobre o versionamento baseado em recursos

Ao documentar qualquer nova alteração ou recurso, use o controle de versão baseado em recursos.

Uma pequena minoria de recursos e alterações só se aplicará a um produto. A maioria dos recursos chega a GitHub.com e, eventualmente, atinge todos os produtos. Em geral, altera o "fluxo" de GitHub.com (incluindo GitHub Enterprise Cloud) para GitHub Enterprise Server.

O controle de versão baseado em recursos fornece "sinalizadores de recursos" nomeados que simplificam a manutenção e o controle de versão da documentação. Você pode usar um único nome de recurso (ou "sinalizador") para agrupar e fazer a prosa de versão em todo o conteúdo. Quando um recurso se trata de produtos adicionais, você só precisa fazer uma alteração no controle de versão YAML no arquivo dentro de data/features/.

Gerenciar recursos

Cada recurso é gerenciado por meio de arquivos YAML individuais no data/features/.

Para criar um novo recurso, primeiro crie um novo arquivo YAML com o nome do recurso que você deseja usar neste diretório. Para um recurso chamado meow, isso seria data/features/meow.yml.

Adicione um bloco versions ao arquivo YAML com os nomes curtos das versões em que o recurso está disponível. Por exemplo:

versions:
  fpt: '*'
  ghec: '*'
  ghes: '>3.1'

O formato e os valores permitidos são os mesmos da propriedade de versões de frontmatter. Para obter mais informações, confira Versões no LEIAME do repositório github/docs.

Condicionais Liquid

Agora você pode usar o {% ifversion meow %} ... {% endif %} em arquivos de conteúdo!

Frontmatter

Você também pode usar o recurso no front matter em arquivos de conteúdo:

versions:
  feature: 'meow'

Você só pode usar uma entrada feature em versions, e o valor de feature só pode conter um nome de recurso.

Você pode combinar o controle de versão baseado em recursos e o controle de versão padrão no front matter. Ao fazer isso, o artigo será incluído no superconjunto de todas as versões especificadas no arquivo de controle de versão baseado em recursos e diretamente no arquivo Markdown. Por exemplo, você pode ter um recurso que atualmente só está disponível no GHEC, e isso é especificado no controle de versão baseado em recursos. No entanto, você deseja que o artigo "Sobre" desse recurso também fique visível nos documentos FPT. Nesse caso, você poderia adicionar fpt e feature ao bloco versions no front matter:

versions:
  fpt: '*'
  feature: 'some-new-feature'

Práticas recomendadas

O conteúdo com controle de versão afeta o leitor, mas também afeta qualquer pessoa que contribua ou revise o conteúdo. Aqui estão algumas dicas para melhorar a experiência de escrita, leitura e revisão para sintaxe de controle de versão. Nenhuma dessas práticas é obrigatória e você encontrará casos de borda e canto, mas elas se destinam a ser heurística útil para ajudá-lo a pensar no controle de versão.

Evitar controle de versão desnecessário

Para o leitor, obter uma compreensão geral é mais importante do que ler detalhes que refletem precisamente as diferenças entre determinados produtos ou planos. Em conteúdo conceitual ou de procedimento, tente descrever recursos ou partes da interface do usuário de maneira geral que não exija sintaxe de controle de versão. Além de ser mais fácil de manter, isso fortalece a compreensão dos leitores que se referem à documentação de vários produtos.

• Pergunte a si mesmo: "Posso escrever este conteúdo de uma maneira que se aplique a todos os produtos sem nenhum controle de versão?"
• Se puder, tente evitar capturas de tela de controle de versão, dado o esforço necessário para criá-las. Pequenas diferenças entre a cópia da interface do usuário podem não afetar a compreensão. Se houver elementos de interface do usuário ou texto específicos do produto, mas a captura de tela ainda fornecer contexto útil, pergunte a si mesmo se o controle de versão das capturas de tela afetará a compreensão em um grau significativo.
• Não faça a prosa de versão se você puder explicar um conceito ou orientar o leitor por meio de um procedimento sem controle de versão para produtos específicos.

Ao modificar um arquivo de conteúdo existente, examine o controle de versão existente antecipadamente e com frequência

Manter-se ciente do controle de versão existente ajudará a garantir que você escreva instruções de controle de versão relevantes e poderá ajudar a lembrá-lo de criar a versão do novo conteúdo com precisão.

• Examine o controle de versão de toda a página no front matter assim que você começar a editar.
• Examine o controle de versão em relação ao conteúdo que você está editando.
• Examine a versão renderizada das alterações que você está fazendo e mude para cada versão disponível da página como parte de sua autorrevisão.

Evitar repetição o máximo possível

Use a sintaxe de controle de versão dentro de uma frase ou parágrafo para diferenciar a prosa para dois planos ou produtos diferentes. Um colaborador pode editar apenas um parágrafo com instruções de controle de versão, em vez de precisar considerar blocos maiores de texto com controle de versão e modificar de modo semelhante em dois lugares, mas com a prosa de controle de versão diferente. O revisor pode sugerir uma alteração uma vez, em vez de precisar deixar a mesma sugestão em vários lugares. Mas se o comportamento difere dramaticamente ou o controle de versão dentro da frase ou do parágrafo se torna complicado ou difícil para análise do colaborador, considere repetir para tornar a prosa mais fácil de manter.

• Use a sintaxe de controle de versão embutida dentro de parágrafos para evitar frases ou parágrafos inteiros repetidos.

  Você pode fazer {% ifversion fpt %}algo{% elsif ghec %}outra coisa{% endif %}.

• Use seu julgamento: para prosa que seria complicada escrever ou ler sem muita sintaxe de controle de versão em uma frase ou parágrafo, considere repetir o parágrafo inteiro em um bloco de versão para cada produto relevante.

  {% ifversion fpt %}

  Se você usar um plano Gratuito, Pro ou de Equipe, poderá fazer algo. Aqui estão mais informações sobre as coisas que você pode fazer com um plano Gratuito, Pro ou de Equipe...

  {% elsif ghec %}

  Se você usar o GitHub Enterprise Cloud, poderá fazer outra coisa. Aqui estão mais informações sobre as coisas que você pode fazer com o GitHub Enterprise Cloud...

  {% endif %}

Seja explícito, não implícito

Se você souber exatamente quais produtos o conteúdo descreve, faça a versão explicitamente desses produtos. A sintaxe como not e else, em particular, pode ser imprecisa. O resultado final de not e else dependem do front matter de cada artigo, portanto, um colaborador deve fazer mais investigação para entender a prosa com esse controle de versão. Isso cria o potencial para erros. A complexidade do controle de versão implícito aumenta em reutilizáveis, em que artigos que fazem referência ao reutilizável podem ter controle de versão diferente e, portanto, avaliações diferentes de not ou else. Ocasionalmente, apresentamos uma nova versão ao GitHub Docs quando o GitHub apresenta um novo produto, o que altera o resultado final de not e else quando adicionamos a nova versão aos artigos existentes.

• Lembre-se de que GitHub oferece quatro produtos e lembre-se de que GitHub Docs pode exibir a documentação para oito versões totais a qualquer momento.
• Examine o controle de versão de um artigo inteiro no front matter quando você começar a editar, pois isso pode ajudá-lo a entender como not e else se comportarão em instruções Liquid ou mudar quando você habilitar novas versões no front matter.

Verificar e comunicar o controle de versão enquanto você trabalha com o design e a criação de conteúdo

Às vezes, uma alteração não é incluída na versão para a qual foi originalmente destinada. Você pode economizar tempo dos revisores e garantir conteúdo mais preciso confirmando o controle de versão em todo o design e criação do conteúdo, para versões e melhorias.

• Considere o controle de versão no design de conteúdo e verifique novamente o controle de versão quando você solicitar revisões de stakeholder para criação de conteúdo.
• Facilite a revisão para outros escritores e stakeholders: aponte diferenças entre as versões em sua solicitação de revisão, vinculando a versões renderizadas específicas do conteúdo, se necessário.
• Confiar sem deixar de verificar.

Testar, testar e testar novamente

Se você estiver escrevendo ou revisando o conteúdo, preste atenção ao plano de design do conteúdo e aos produtos afetados e verifique o conteúdo renderizado em um ambiente de preparo ou desenvolvimento para garantir que ele descreva cada produto com precisão.