Versioning and breaking changes

[davicostalf]

Comentários no CSAT de Engenharia em 2023 H1:

Acredito que ainda falta maturidade do design system, ainda não é algo que considero estável, temos que trabalhar com versão em freeze para evitar breaking changes grandes.

Breaking changes são muito frequentes. Isso torna a manutenção do projeto difícil, mesmo com codemods e guias de migração disponíveis.

O time é top e está sempre melhorando a lib, mas é difícil de se manter atualizado com as frequentes breaking changes, mesmo com codemods, pois requerem que alguém pare pra tratar dela com cuidado (ao invés de apenas mergear o update, por exemplo).

Senti dificuldade de adaptação entre versões do Admin-UI acho que poderia ser mais adaptável.

Cada lançamento de uma nova versão é um pequeno momento de apreensão de quantas breaking changes terá.

O Admin UI acaba ajudando bastante na implementação de componentes e é bem fácil de usar.
Porém, a quantidade de mudanças feitas em um intervalo curto fez com que um dos projetos que eu trabalho se tornasse um problema grande, visto que não conseguíamos acompanhar atualizar enquanto as mudanças estavam sendo executadas e, por isso, não conseguimos usar algumas features da lib.

No VTEX IO, já observei problemas com incompatibilidade, por exemplo, problemas na versão 0.136.0, em relação a tipagem do modal (comentado no canal #admin-ui que o problema deve ser com o TypeScript legado do VTEX IO).
Além disso, as atualizações do DS, costumam ser tarefas demoradas por necessitar fazer grandes ajustes a cada atualização, mesmo sendo entre versões próximas e até consecutivas.

Eu entendo que tem um tanto de breaking change, mas acho que faz parte. São sempre justificadas, documentadas e bem vindas. A 0.135 acrescentou tokens de spacing.
Deu um trabalho mudar, mas só deu trabalho porque antes, no mesmo projeto, eu fazia o espaçamento de várias formas e agora tem uma única forma de fazer.

Para aplicações grandes, cada breaking change é re-trabalho de 2 sprints. Somando isto ao trabalho já mapeado dos Hs/Q/Ciclos fica demasiadamente puxado.

É muito tranquilo desenvolver com o admin-ui mas dentro das versões do próprio admin-ui, ao atualizar a versão, tem vezes que temos de fazer muitas modificações no código.

Updating an app to use the latest or more recent versions of Admin UI can be considerable effort if the app was developed using an earlier version of the Admin UI.
There's a large number of changes between versions, including deprecated components. Incrementally switching to components from the latest version of Admin UI while using older components in other parts of the app is difficult, if not impossible.
The new components solve issues of older components but cannot be used without a lot of refactoring.

We are early adopters and the visual breaking changes (thematization) impact our implementations at UI level needing review of the designers.

Versioning is constantly changing, but major version change management with break changes has a direct impact on development, because when we update the admin-ui in the project, things that worked end up not working. This happens because we need to update to fix a problem, or get new components, and we end up being impacted by changes at various points in the project.

Another point is the question of figma's design, which evolves along with the most up-to-date versions of the admin-ui, but the code base of our projects and the day-to-day demands do not allow us to always leave with the latest version, generating differences in the that was designed by the design team, in relation to what was implemented.

entre uma versão e outra acaba tendo inconsistências (o que é normal, pois não temos uma versão ok ainda) mas acaba 'quebrando' o código e levando mais tempo que o normal para ajustar tudo.

A remoção da doc de versões mais antigas também apresenta um problema.

A documentação é boa. Sugiro incluir mais detalhes e exemplos nos componentes que podem utilizar chamadas async, uma atenção redobrada nas breaking changes (deixar claro o impacto dessas mudanças), aos componentes obsoletos e a eventuais tokens que não funcionam corretamente.