Várias versões

Uma ref torna-se uma versão. Aponta uma fonte para tags e cada uma é publicada, com um segmento de versão no URL e uma entrada no seletor.

Os refs exigem um repo explícito, mesmo para publicar outro ref deste repositório. Sem repo, a fonte lê o checkout local atual e rejeita refs (incluindo latest) e substituições locais de ref por idioma. origin.repo e origin.ref fornecem apenas ligações de proveniência; não selecionam conteúdo. Um idioma com o seu próprio repo explícito pode escolher o seu próprio ref. Para versões locais, use version em fontes com pastas distintas ou as versions por ficheiro de uma secção gerada.

#Passos

#A granularidade de uma versão

O nome é uma escolha do site, não do mecanismo, e é a decisão mais importante aqui: todas as ligações à tua documentação o vão conter.

Uma linha por versão, como ramo. É o que fazem Laravel, Symfony e Django: 11.x, 10.x e 9.x são ramos que continuam a avançar, e um lançamento de correção não altera o URL.

sources: [
  {
    repo: 'acme/api',
    path: 'docs',
    refs: [
      { branch: '12.x', status: 'upcoming' },
      '11.x',
      { branch: '10.x', status: 'deprecated' },
      { branch: '9.x', status: 'eol' }
    ]
  }
],
sourceOptions: { defaultRef: '11.x' }

Um texto simples é um ramo; só uma tag tem de o declarar.

Uma linha por versão, a partir de tags. Quando o lançamento a publicar é uma tag mas o URL não deve mudar a cada correção, label dá-lhe outro nome:

refs: [
  { tag: 'v2.4.1', label: 'v2' },
  { tag: 'v1.9.3', label: 'v1', status: 'deprecated' }
]

Cada lançamento com a sua versão. { tag: 'v2.4.1' } sem rótulo. Cada um pode ser citado para sempre e o seletor cresce uma entrada por lançamento — adequado para uma especificação, mas não para um manual.

As mesmas políticas podem ser mantidas a partir das tags em vez de repetidas na configuração:

// Cada lançamento que deve continuar citável.
releases: { select: 'all' }

// Ou a correção mais recente de cada linha minor duradoura.
releases: { select: 'minor' }

// Ou um lançamento atual por cada linha major.
releases: { select: 'major' }

O lançamento selecionado mais recente é o predefinido, salvo se uma ref explícita com default: true ou sourceOptions.defaultRef indicar outra coisa. Uma seleção sem tags correspondentes faz a compilação falhar; um repositório inacessível é reportado como erro de Git, não confundido com uma seleção vazia.

A mesma escolha aplica-se a uma secção com versões próprias: version: 'v2' ou version: '2.4.1', com exatamente o mesmo compromisso. Um modelo, uma decisão, quer o conteúdo venha de uma ref ou de um ficheiro.

#Quando as versões não são refs

Uma versão é normalmente um checkout. Duas formas comuns não o são:

Documentação em pastas. docs/v1 ao lado de docs/v2 num repositório, sem tags. Cada fonte nomeia a sua versão:

sources: [
  { path: 'docs/v2', version: 'v2' },
  { path: 'docs/v1', version: 'v1', status: 'deprecated' }
]

Uma API em ficheiros. openapi/v1.yaml ao lado de openapi/v2.yaml é a forma habitual de manter uma API. As versões pertencem à secção, não à fonte:

generated: [
  {
    type: 'openapi',
    label: 'API',
    path: 'openapi/v2.yaml',
    versions: [
      { version: 'v2', path: 'openapi/v2.yaml' },
      { version: 'v1', path: 'openapi/v1.yaml', status: 'deprecated' }
    ]
  }
]

Ambas produzem exatamente o mesmo que as refs: um segmento no URL, uma entrada no seletor, o aviso e o canonical. O seletor fica limitado ao artefacto que lês: em /api oferece as versões da API; numa página de prosa, as da documentação.

#O que acontece às versões antigas

Uma versão não predefinida leva noindex e um canonical a apontar para a mesma página na predefinida, e uma versão eol sai completamente do sitemap. É isso que impede um motor de busca de oferecer v0.9.0 onde o leitor queria a documentação de hoje — ver URL e versões.

#Lista de verificação

• Cada tag está escrita como { tag: … }, não como texto simples
• Os nomes das versões têm a granularidade das linhas de suporte do projeto
• defaultRef nomeia a versão onde os leitores devem aterrar
• Um ramo na lista traz um status explícito
• O seletor mostra todas as versões, com distintivo nas mortas
• A página de uma versão morta não está em /sitemap.xml
• Se as versões são pastas ou ficheiros em vez de refs, usa-se exatamente um de refs, version de uma fonte e versions de uma secção