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

::steps
1. **Lista as refs.** Um texto simples é um **ramo**. Uma tag tem de o dizer — o
   git mantém os dois em espaços de nomes separados, e pedir uma tag sob
   `refs/heads` faz a compilação falhar.

   ```ts [app/app.config.ts]
   sources: [
     {
       repo: 'acme/api',
       path: 'docs',
       refs: [
         { branch: 'main', status: 'upcoming' },
         { tag: 'v2.0.0' },
         { tag: 'v1.4.0' },
         { tag: 'v0.9.0', status: 'eol' }
       ]
     }
   ],
   sourceOptions: { defaultRef: 'v2.0.0' }
   ```

2. **Nomeia a predefinida.** `defaultRef` é a ref servida sem prefixo de versão
   e aquela para onde os motores de busca são apontados. Se não for definida, é
   a primeira da lista — o que raramente é o que queres quando a lista começa
   por um ramo.

3. **Declara o ciclo de vida onde não pode ser deduzido.** O semver ordena tags,
   por isso «mais antiga do que a predefinida» não precisa de ajuda. O que não
   consegue é situar um ramo face a uma tag: `main` é `upcoming`, e sem o dizer
   pede-se ao seu leitor que atualize para uma versão mais antiga do que aquela
   que está a ler.

4. **Descobre versões se não quiseres editar a lista a cada lançamento.**
   Escolhe quanto histórico deve continuar endereçável: todas as versões, o
   patch mais recente de cada linha minor ou a versão mais recente de cada linha
   major.

   ```ts
   releases: { select: 'minor' },
   refs: [{ branch: 'main', status: 'upcoming' }]
   ```

   `all`, `minor` e `major` são políticas para URLs duradouros. As pré-versões
   ficam de fora salvo com `prereleases: true`. Para uma única versão móvel,
   `'latest'` continua disponível.

5. **Assinala o requisito de versão de uma página no texto**, onde quem olha
   para uma versão não consegue ver as outras:

   ```md
   ### Novas tentativas :since{version="v2.0.0"}
   ```

::

## 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.

```ts [app/app.config.ts]
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:

```ts
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:

```ts
// 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.

::callout{type="tip" title="Nomes mais gerais envelhecem melhor"}
Um segmento de versão faz parte de cada ligação à tua documentação.
`v2` sobrevive aos próximos quarenta lançamentos; `2.4.1` fica desatualizada no
dia em que sai `2.4.2`.
::

## 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:

```ts [app/app.config.ts]
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:

```ts [app/app.config.ts]
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.

::callout{type="warning" title="Uma das duas, nunca ambas"}
Uma fonte com `refs` **e** `version`, ou uma secção com `versions` numa fonte com
refs, faz a compilação falhar: ambas reclamam o mesmo segmento do URL.
Consulta a lista completa de campos em [Fontes](/reference/sources).
::

## 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](/concepts/urls-and-versions).

## 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