Marcus Andrey Estudo
Read in English Biblioteca

Framework · Design systems · 3 min de leitura

Versionamento semântico para design systems

MAJOR.MINOR.PATCH aplicado a um design system, em que a API inclui nomes, padrões, layout e comportamento, para que cada número de release diga aos times de produto com quanto cuidado atualizar.

4MAJOR

Algo que funcionava ontem quebra ou muda de cara sem ninguém mexer.

ex.: uma prop renomeada, um padrão alterado
.5MINOR

Novo e compatível, inclusive o que acaba de ser marcado como descontinuado.

ex.: um componente novo, um aviso de descontinuação
.1PATCH

Uma correção compatível que devolve o que a documentação promete.

ex.: o anel de foco de volta a 2 px

MAJOR.MINOR.PATCH · API = nomes + padrões + layout + comportamento · 0.y.z: tudo pode mudar

Cada número diz aos times de produto com quanto cuidado atualizar; num design system, a API é tudo em que um produto confia sem pensar.

Use quando

  • Você está para fazer um release e alguém diz "é só um ajuste visual, chama de patch".
  • Os times pararam de atualizar porque não sabem distinguir um release seguro de um arriscado.
  • A biblioteca do Figma e o pacote de código foram parar em números diferentes.

Como usar

  1. Escreva o que conta como API. Num design system, isso são os nomes (componentes, props, valores de opção, tokens, CSS custom properties, nomes de propriedades no Figma), os padrões, o layout e o comportamento. Coloque a lista na documentação. Resultado: uma seção curta "a nossa API pública".
  2. Classifique cada mudança com uma pergunta. Algo que funcionava ontem vai quebrar ou mudar de cara sem ninguém mexer? Sim é MAJOR. Um recurso novo e compatível, ou uma nova descontinuação, é MINOR. Uma correção compatível é PATCH. Resultado: um rótulo em cada mudança integrada.
  3. Descontinue numa minor, remova numa major. O Semantic Versioning pede pelo menos um release minor com a descontinuação antes da major que remove. Resultado: nenhuma remoção sem um release descontinuado antes.
  4. Dê um número só para Figma e código. Versione o pacote, comece a descrição da publicação da biblioteca com o mesmo número e mostre a versão atual na capa de cada arquivo da biblioteca. Resultado: "estamos na 3.0" quer dizer a mesma coisa para design e engenharia.
  5. Escreva o changelog para pessoas. O mais novo primeiro, agrupado em Added, Changed, Deprecated, Removed, Fixed e Security. Numa major, inclua o que usar no lugar, quanto tempo a atualização leva num produto real e onde pedir ajuda. Resultado: notas de release com que uma designer ocupada consegue agir.
  6. Mantenha um ritmo que os times possam planejar. Minors numa cadência fixa, patches quando precisar (correções de acessibilidade não devem esperar), majors raras e anunciadas cedo, design e código no mesmo dia. Resultado: um calendário de releases na documentação.

Exemplo prático

O Harbour está na 3.4.0. Cinco mudanças esperam o próximo release na Tidewater:

Mudança Quebra ou muda de cara sem ninguém mexer? Número
Anel de foco do Text field de volta a 2 px depois de uma regressão Não, devolve o visual documentado PATCH
Novo componente Notice Não, nada do que existe muda MINOR
Banner marcado como descontinuado, o aviso cita Notice Não, continua funcionando MINOR
O padding do Button cresce, e ele fica 4 px mais alto Sim, os formulários se reorganizam em todas as telas MAJOR
A prop kind do Button vira variant Sim, os builds falham MAJOR

As três primeiras saem juntas como 3.5.0. As duas do Button esperam a 4.0.0, anunciada com data e guia de migração.

Cuidado com

  • Chamar mudança visual de patch. "A API não mudou" é o teste errado. Layout e padrões são API.
  • Majors tão frequentes que os times param de atualizar. Junte as breaking changes num ritmo conhecido.
  • Ficar anos na 0.y.z. A versão 0 quer dizer "tudo pode mudar a qualquer momento", então nada fica prometido.
  • Changelog copiado das mensagens de commit. "Fixed focus ring" é commit. "Text field: anel de foco de volta a 2 px" é linha de changelog.

Modelo

Copie no checklist de release e preencha antes de escolher o número.

Versão atual: ...
Mudanças neste release:
  - ...  | quebra ou muda de cara sem ninguém mexer? sim / não | MAJOR / MINOR / PATCH
  - ...
Nova versão: vale o maior salto = ...

Notas de release (mais novo primeiro)
## [x.y.z] - AAAA-MM-DD
### Added       ...
### Changed     ...
### Deprecated  ... (use ... no lugar, removido na ...)
### Removed     ... (use ... no lugar)
### Fixed       ...
### Security    ...
Quem é afetado: ...
Tempo de atualização num produto real: ...
Ajuda: guia de migração ... / plantão ... / canal ...

A descrição da publicação no Figma começa com: "x.y.z: ..."
Fonte
Semantic Versioning 2.0.0 (Tom Preston-Werner). Keep a Changelog 1.1.0 (Olivier Lacan)

Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.

Salvo só neste dispositivo.

↑ ↓ para mover · Enter para abrir · Esc para fechar