Esquema e componentes

O tipo changelog escreve páginas Markdown comuns cujos corpos são dois componentes MDC, renderizados dentro de um esquema próprio. Os três estão documentados porque fazem parte da superfície pública — um consumidor pode substituir qualquer um deles — não porque uma página tenha de ser escrita à mão.

#O esquema changelog

Ligado apenas à granularidade split; um registo plano é uma página de documentação comum e renderiza no enquadramento da documentação.

Difere de docs em dois pontos, e ambos seguem do que as páginas são. A barra lateral é a lista de versões em vez de uma árvore de prosa — a mesma navegação, a mesma coleção, porque uma secção gerada é uma coleção comum e as suas páginas são as versões. E a coluna de leitura está limitada a uma medida: uma nota de versão é prosa, e prosa composta ao longo de toda a janela é ilegível. A coluna de conteúdos fica, listando os grupos.

Substitua-o por um ficheiro seu no mesmo caminho:

app/layouts/changelog.vue

#ChangelogReleases

A cronologia da vista geral: cada versão, a mais recente primeiro, filtrável pelo que mudou. Escrito na página de índice da secção.

O histórico abre com quatro indicadores: versões, alterações, contribuidores e data do último lançamento, numa grelha de quatro colunas a toda a largura. A data é o único valor que não é uma contagem; se o ficheiro não tiver datas, desaparece em vez de mostrar um traço. Os indicadores mostram a dimensão do histórico, que as linhas isoladas não comunicam. Contam o que é mostrado: após filtrar, descrevem a página filtrada, mantendo o total ao lado do primeiro indicador; ao filtrar alterações incompatíveis, o número de contribuidores diz quem já entregou uma.

#De onde vêm os contribuidores

Não vêm do changelog, mas do intervalo git entre a tag anterior e esta versão. São tentadas as formas 1.2.0 e v1.2.0. Commits de merge definem limites, mas não recebem crédito como alteração própria; contas marcadas como apps ficam de fora.

O rótulo leva o destaque, não o número: --primary é a cor que o site consumidor escolhe para personalizar o tema, e duas pequenas linhas de rótulo podem recebê-la sem custo visual.

Abaixo, cada versão ocupa uma linha em colunas: versão, emblema, conteúdo, data. As versões ficam alinhadas e os resumos começam na mesma posição. Abaixo de sm, o resumo passa para uma segunda linha; nada desloca horizontalmente. O emblema de versão atual fica junto ao número, numa coluna fixa que existe mesmo vazia, para que os resumos das versões sem emblema comecem no mesmo sítio. A data fica na extremidade, junto à seta: o leitor percorre esse campo na vertical em vez de o ler ao longo da linha.

A filtragem anima os dois lados: as fichas acima da lista e as linhas que se movem abaixo, com as mesmas durações para parecerem um só gesto. As linhas esbatem-se e assentam em 200 ms. Uma linha que sai é retirada do fluxo, permitindo que as seguintes fechem o espaço enquanto desaparece; o FLIP do navegador move as restantes. Usa-se uma TransitionGroup, sem biblioteca de animação: um esbatimento e um pequeno movimento não justificam uma dependência de execução em cada site consumidor. Tudo fica desligado com prefers-reduced-motion. Uma linha nomeia os três maiores grupos e conta os restantes: «Features 2 · Bug Fixes 2 · Documentation 1 · e mais 9». Três, por contagem, não pela ordem fixa das secções do release-please, que não indica importância. Nada é omitido em silêncio; uma linha filtrada nomeia primeiro aquilo por que foi filtrada.

A cor fica onde distingue em vez de decorar: no menu de filtros e no rótulo de cada grupo na página da versão, não no histórico.

Uma marca antes do nome é retirada na apresentação, onde quer que o nome apareça: o ⚠ que precede o bloco de alterações incompatíveis do release-please ou um emoji no início de uma secção mantida à mão. Só no início, para preservar C++ Support. O nome guardado fica inteiro: o filtro compara-o, a âncora deriva dele e as props transportam-no. Por isso a remoção pertence à apresentação e não ao analisador. Ver changelogLabel.

Os groups de uma versão trazem apenas um name e um count — as entradas não estão aqui, porque cada versão tem uma página própria e repetir os seus pontos meteria o histórico inteiro duas vezes no índice de pesquisa, no llms-full.txt e no feed.

As fichas de filtro são construídas a partir dos nomes que o próprio ficheiro usou. Sem nada selecionado a página mostra tudo, que é também o que o servidor renderiza: um filtro é a escolha de um leitor, portanto a página tem de estar completa antes de alguém fazer uma — caso contrário o rastreador e o leitor cuja hidratação ainda não chegou recebem cada um um registo filtrado que ninguém pediu.

#ChangelogGroup

Um grupo de uma versão — «Features», «Bug Fixes», o que o ficheiro dissesse.

As entradas chegam no slot, como o Markdown em que foram escritas — assim a pesquisa indexa-as, o llms-full.txt leva-as e o botão de cópia entrega a um modelo prosa em vez de uma chamada de componente. Só o nome e o número, de que o emblema e os filtros precisam como dados, viajam como props.

O nome é um rótulo, não um título de destaque: pequeno, em maiúsculas e na tonalidade do grupo, acima de uma lista compacta. Com 20 píxeis, uma palavra para quatro pontos tinha o peso de um capítulo, e seis grupos pareciam seis secções em vez de uma versão. Continua a ser um <h2>: estrutura, coluna de conteúdos e âncora não mudam; só a composição ajusta a importância visual.

A cor é uma pista e nunca um significado: um nome desconhecido recebe a sua própria cor estável, tornando o mesmo tipo de alteração percorrível numa página de quarenta versões em qualquer idioma. O rótulo usa o par text da tonalidade em vez do preenchimento dot: palavras e um ponto de seis píxeis não atingem o contraste necessário com a mesma luminosidade.

Os marcadores das entradas ficam cinzentos. A cor já aparece no rótulo acima; repetida em cada linha deixa de ser um sinal. Os marcadores são definidos em duxt.css, não neste componente, porque chegam como Markdown através do slot.

#Substituir um

Como para qualquer outro componente que a camada traz: ganha um ficheiro no mesmo caminho no site consumidor.

app/components/content/ChangelogGroup.vue

As props acima são o contrato, e o nome do esquema também. Uma mudança de nome aqui é uma alteração incompatível da camada.

#O que uma página de versão mostra além dos grupos

Nada no corpo. A data do lançamento e o diff de que a versão resultou viajam como date e compare no frontmatter. São apresentados onde o site já explica a origem de uma página: no bloco de proveniência sob a coluna de conteúdos, acima de «Editar esta página».

A data da versão substitui a linha do último commit: todas as versões de um registo vivem num ficheiro, cujo último commit lhes daria a todas a mesma data — na melhor hipótese, a da versão mais recente.

Assim, uma página de versão lê-se como qualquer outra página Markdown do site: uma nota de versão é prosa, não um painel de indicadores.

#Sem título próprio

Nenhum dos dois componentes abre com um <h1>. O enquadramento da documentação desenha o cabeçalho — navegação estrutural, título, o botão de cópia ao lado — para toda a página gerada cujo corpo não abre com um título, e uma página de versão quer exatamente isso: um título e um rasto como qualquer página escrita.