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.
Algo que funcionava ontem quebra ou muda de cara sem ninguém mexer.
ex.: uma prop renomeada, um padrão alteradoNovo e compatível, inclusive o que acaba de ser marcado como descontinuado.
ex.: um componente novo, um aviso de descontinuaçãoUma correção compatível que devolve o que a documentação promete.
ex.: o anel de foco de volta a 2 pxMAJOR.MINOR.PATCH · API = nomes + padrões + layout + comportamento · 0.y.z: tudo pode mudar
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
- 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".
- 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.
- 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.
- 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.
- 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.
- 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: ..."
- Atomic DesignBrad FrostLivro · 2016 (Amazon)
- Semantic Versioning 2.0.0 (site externo)
- Keep a Changelog 1.1.0 (site externo)
- Atomic Design, capítulo 5: Maintaining design systemsBrad Frost (site externo)
Os links "Ver na Amazon" são de afiliado: como associado, recebo por compras qualificadas, sem custo a mais para você.