docs: add designer handboek "breaking changes" #1151
Conversation
|
The latest updates on your projects. Learn more about Vercel for Git ↗︎
|
|
|
||
| ### Situatie B: in je eigen repository | ||
|
|
||
| <!-- @todo willen we dit onderscheid? --> |
There was a problem hiding this comment.
Vragen die ik na het lezen zelf nog heb:
- Wat nu als de design token gaat plaats maken voor een vaste waarde? button.border-width krijgt in css een fixed value (border-width: 1px) want is bijvoorbeeld een best practise en blijkt (bij candiate) voor elke org zo prima te werken?
- Wat nu als dit ook aan de code kant wordt doorgevoerd? Nog steeds breaking?
- Wat nu als er juist een breaking change aan de code kant wordt doorgevoerd? Hoe weet ik dat als designer? Keertje proefdraaien?
matijs
force-pushed
the
docs/designer-breaking-changes
branch
from
af8dd6d
to
92a65de
Compare
matijs
force-pushed
the
docs/designer-breaking-changes
branch
from
92a65de
to
e61caf2
Compare
matijs
force-pushed
the
docs/designer-breaking-changes
branch
from
e61caf2
to
6c737d2
Compare
|
|
||
| Deze packages worden geüpload naar een package registry. Een package registry is een database van alle packages die ooit zijn geüpload. | ||
|
|
||
| Alle packages in een registry hebben een versienummer. Als er een nieuwe versie van een package wordt geüpload wordt daarvoor het versienummer van het package opgehoogd. |
There was a problem hiding this comment.
Misschien kan deze zin iets versimpeld worden?
... wordt daarvoor het versienummer van het package opgehoogd. -->
... wordt het versienummer van dat package opgehoogd.
|
|
||
| ## Semantic versioning in een notendop | ||
|
|
||
| Bij NL Design System maken we voor het ophogen van versienummers gebruik van ‘semantic versioning’ ook wel bekend als semver. Binnen semver bestaat een versienummer uit drie delen: `major.minor.patch` (bijvoorbeeld `1.0.0`). |
There was a problem hiding this comment.
Een voorbeeld met een minder mooi versienummer spreekt misschien nog meer tot de verbeelding?
(bijvoorbeeld 1.0.0) --->
(bijvoorbeeld 1.3.2).
|
|
||
| Het ophogen van het patch deel van het versienummer gebeurt in de regel als er bugs zijn opgelost. Deze veranderingen zijn altijd achterwaarts compatibel. Bij het verhogen van het patch deel van het versienummer blijven het major en minor deel hetzelfde. | ||
|
|
||
| Een versienummer alleen zegt niet zo veel. Door de versienummers met elkaar te vergelijken kun je als afnemer van een package zien wat de impact is van de veranderingen op code die gebruik maakt van het package. |
There was a problem hiding this comment.
Is het een idee om voorafgaand aan deze zin een kopje te plaatsen zodat deze zin 'los' komt te staan van de tekst over 'Patch'? Suggestie:
Wat kun je met een versienummer?
Een versienummer alleen zegt niet zo veel. Maar door versienummers met elkaar te vergelijken...
| @@ -0,0 +1,137 @@ | |||
| --- | |||
| title: Breaking changes | |||
There was a problem hiding this comment.
Omdat de documentatie niet langer alleen over 'Breaking changes' gaat twijfel ik over de titel. Wat denk jij, zou een titel als 'Versiebeheer voor design tokens' deze documentatie beter samenvatten?
|
|
||
| Breaking changes in design tokens zijn veranderingen die voor afnemers van je package negatieve gevolgen kunnen hebben. Het zijn veranderingen die niet achterwaarts compatibel zijn waardoor bestaande code niet meer werkt zoals voorheen. | ||
|
|
||
| Het resultaat hiervan is op de een of andere manier kapot. Soms is dit heel duidelijk, bijvoorbeeld spacing die helemaal is verdwenen. Soms is het subtieler en misschien niet meteen zichtbaar, een hover kleur die is aangepast. |
There was a problem hiding this comment.
Zou deze zin ook kloppen?
Het resultaat hiervan is op de een of andere manier kapot.
--> Er gaat op een of andere manier iets kapot.
There was a problem hiding this comment.
'...een hover kleur die is aangepast.'
Ik snap dat deze wijziging subtiel en minder zichtbaar is. Maar in de tekst lijkt het nu dat de 'waarde' van de tokens is aangepast, niet de 'naam' van de token. Das niet breaking toch? Die waarde is namelijk voor iedere organisatie zelf in te stellen.
There was a problem hiding this comment.
Ik laat het voor nu weg. Misschien dat we nog een keer een beter voorbeeld kunnen bedenken.
| 1. Laat het oude design token `example.button.icon.space` verwijzen naar de waarde van de nieuwe design token: `{example.button.column-gap}`. | ||
| 1. Markeer de oude design token `example.button.icon.space` als ‘deprecated’ bijvoorbeeld door er een sticker bij te zetten of door de beschrijving aan te passen. | ||
|
|
||
| Doordat je de oude token niet verwijdert maar markeert als ‘deprecated’ vertel je gebruikers die de design token al gebruiken dat ze voor nieuwe code de design token niet meer moeten gebruiken en dat ze bestaande code zullen moeten aanpassen. Hoe code moet worden aangepast geef je aan in een changelog. Meer daarover hieronder. |
There was a problem hiding this comment.
Lange zin. Voorzetje
Doordat je de oude token niet verwijdert maar markeert als ‘Deprecated’ informeer je afnemers van de design token dat ze deze design token niet meer moeten gebruiken. En dat ze bestaande code moeten gaan aanpassen
There was a problem hiding this comment.
Het is belangrijk om het onderscheid tussen nieuwe en bestaande code te hebben denk ik. Als je alleen maar zegt dat het niet meer gebruikt moet worden dan lijkt me dat mensen kunnen denken dat ze meteen nieuwe code moeten aanpassen. Deprecation zorgt er juist voor dat dat iets minder urgent is.
Ik heb er twee wat kortere zinnen van gemaakt.
|
|
||
| Doordat je de oude token niet verwijdert maar markeert als ‘deprecated’ vertel je gebruikers die de design token al gebruiken dat ze voor nieuwe code de design token niet meer moeten gebruiken en dat ze bestaande code zullen moeten aanpassen. Hoe code moet worden aangepast geef je aan in een changelog. Meer daarover hieronder. | ||
|
|
||
| Stel de huidige versie van je package is 1.x.x en je wilt op termijn een design token verwijderen. Afnemers van het package die nu versie 1.x.x gebruiken zien |
There was a problem hiding this comment.
Deze zin is nog niet af gok ik?
There was a problem hiding this comment.
Ja, weggehaald. Ik denk dat wij eerst moeten bepalen hoe de tijdslijn voor deprecation er ongeveer uit zou moeten zien voor ik er wat zinnigs over kan schrijven.
|
|
||
| Stel de huidige versie van je package is 1.x.x en je wilt op termijn een design token verwijderen. Afnemers van het package die nu versie 1.x.x gebruiken zien | ||
|
|
||
| ## Communiceer over je veranderingen |
There was a problem hiding this comment.
Hier kan misschien nog iets van een intro bij? Voorzet:
Jij weet wat je verandert hebt. De afnemer van de design tokens niet. Het is dus wel zo netjes om afnemers te informeren over veranderingen. We leggen je uit hoe je deze communicatie kan aanpakken.
There was a problem hiding this comment.
Goed idee. Zou daarvan maken:
Jij weet wat je hebt veranderd, maar de afnemer van de design tokens niet. Het is dus wel zo netjes om afnemers te informeren over de veranderingen. We leggen je uit hoe je deze communicatie kunt aanpakken.
|
|
||
| Als je een [pull request hebt aangemaakt](/handboek/designer/stappenplan/#verstuur-aanpassingen-naar-github) geef je daar met een extra commit aan wat je precies veranderd hebt. De beschrijving die je hierbij opgeeft komt terecht in de changelog van het package. | ||
|
|
||
| ### Situatie A: in het NL Design System “themes” repository |
There was a problem hiding this comment.
Misschien de stappen even introduceren?
Situatie A: NL Design System “themes” repository
Werk je vanuit de NL Design System “themes” repository? Volg dan onderstaande stappen.
| Deprecated design token example.button.icon.spacing verwijderd | ||
| ``` | ||
|
|
||
| ### Situatie B: in je eigen repository |
There was a problem hiding this comment.
En dan hier ook?
Situatie B: Eigen repository
Werk je vanuit een eigen repository? Volg dan onderstaande stappen.
|
|
||
| Deze packages worden geüpload naar een package registry. Een package registry is een database van alle packages die ooit zijn geüpload. | ||
|
|
||
| Alle packages in een registry hebben een versienummer. Als er een nieuwe versie van een package wordt geüpload wordt het versienummer van het package opgehoogd. |
There was a problem hiding this comment.
Ik zou een komma toevoegen na het woord 'wordt' in de 2e zin, dus:
Als er een nieuwe versie van een package wordt geüpload, wordt…
| ## Semantic versioning in een notendop | ||
|
|
||
| Bij NL Design System maken we voor het ophogen van versienummers gebruik van ‘semantic versioning’ ook wel bekend als semver. Binnen semver bestaat een versienummer uit drie delen: `major.minor.patch` (bijvoorbeeld `1.3.2`). | ||
|
|
There was a problem hiding this comment.
Ik zou de zin veranderen naar:
Bij NL Design System gebruiken we het voor ophogen van versienummers 'semantic versioning', ook wel bekend als semver.
Heb er ook een interpunctie aan toegevoegd.
|
|
||
| Breaking changes in design tokens zijn veranderingen die voor afnemers van je package negatieve gevolgen kunnen hebben. Het zijn veranderingen die niet achterwaarts compatibel zijn waardoor bestaande code niet meer werkt zoals voorheen. | ||
|
|
||
| Er gaat op de een of andere manier iets kapot. Soms is dit heel duidelijk, bijvoorbeeld spacing die helemaal is verdwenen. Soms is het subtieler en misschien niet meteen zichtbaar. |
There was a problem hiding this comment.
'Zoals' toegevoegd:
Soms is dit heel duidelijk, zoals bijvoorbeeld…
|
|
||
| Er gaat op de een of andere manier iets kapot. Soms is dit heel duidelijk, bijvoorbeeld spacing die helemaal is verdwenen. Soms is het subtieler en misschien niet meteen zichtbaar. | ||
|
|
||
| Breaking changes zijn zoals [hierboven uitgelegd](#major), veranderingen die ervoor zorgen dat het **major** deel van het versienummer opgehoogd moet worden. |
There was a problem hiding this comment.
Kunnen we de laatste alinea bovenaan zetten? Ik merk dat die herhaling aan het begin fijner is om de context eronder beter te snappen. Dus:
Breaking changes zijn zoals hierboven uitgelegd, veranderingen die ervoor zorgen dat het major deel van het versienummer moet worden opgehoogd.
Deze veranderingen kunnen negatieve gevolgen hebben voor afnemers van je package. Dit zijn veranderingen die niet achterwaarts compatibel zijn, waardoor bestaande code niet meer werkt zoals voorheen.
Als je deze structuur aanhoudt, kun je mijn comment hierboven over de 1e alinea negeren.
|
|
||
| Breaking changes zijn zoals [hierboven uitgelegd](#major), veranderingen die ervoor zorgen dat het **major** deel van het versienummer opgehoogd moet worden. | ||
|
|
||
| #### Voorbeelden van breaking changes in design tokens |
There was a problem hiding this comment.
Lijkt me heel goed om daar voorbeelden voor te bedenken.
Kunnen we later misschien een tabel of lijst of iets anders opstellen en deze categoriseren op basis van major, minor en patch changes?
Op die manier kunnen gebruikers snel zien welke impact verschillende updates kunnen hebben op hun code.
| Een ander soort breaking change die hier op lijkt is als je de naam van een design token verandert. Dit lijkt misschien een minder grote verandering dan het verwijderen van een design token maar in feite komt het neer op: | ||
|
|
||
| 1. Het verwijderen van een design token. | ||
| 1. Het toevoegen van een nieuw design token. |
| 1. Het verwijderen van een design token. | ||
| 1. Het toevoegen van een nieuw design token. | ||
|
|
||
| **Voorbeeld 2**: Het hernoemen van de design token `example.button.icon.space` naar `example.button.column-gap` zorgt ervoor dat de design token `example.button.icon.space` niet meer bestaat. Net als in het vorige voorbeeld gaat de button door deze verandering kapot als een afnemer van het package gebruik maakt van de verwijderde design token. |
There was a problem hiding this comment.
Als we uitgaan van knop i.p.v. button, dan moeten we dat woord hier ook nog aanpassen.
| 1. Het verwijderen van een design token. | ||
| 1. Het toevoegen van een nieuw design token. | ||
|
|
||
| **Voorbeeld 2**: Het hernoemen van de design token `example.button.icon.space` naar `example.button.column-gap` zorgt ervoor dat de design token `example.button.icon.space` niet meer bestaat. Net als in het vorige voorbeeld gaat de button door deze verandering kapot als een afnemer van het package gebruik maakt van de verwijderde design token. |
There was a problem hiding this comment.
Zou van de laatste zin maken:
Net als in het eerste voorbeeld kan dit ervoor zorgen dat de knop niet meer naar behoren functioneert voor afnemers die de verwijderde design token gebruiken.
|
|
||
| **Voorbeeld 3**: Het aanpassen van zelfs maar 1 karakter in de naam van een design token, bijvoorbeeld het corrigeren van een typfout `colour` naar `color`, kan al een breaking change zijn. | ||
|
|
||
| Breaking changes zijn, ondanks dat hun naam het doet vermoeden, niet per se erg. Het is alleen heel belangrijk om er duidelijk over te communiceren. Daarover later meer. |
There was a problem hiding this comment.
Zou hiervan maken:
Breaking changes zijn, ondanks hun naam, niet per se problematisch. Het is echter van groot belang om hier duidelijk over te communiceren. Daarover meer informatie later.
| 1. Klik rechtsboven op ‘Commit changes…’. | ||
| 1. Geef een commit message op, bijvoorbeeld ‘Changeset toegevoegd’. | ||
| 1. Kies onderaan voor ‘Commit directly to the `{naam-van-je-branch}`’ branch. | ||
| 1. Klik op ‘Commit changes’. Als je hier een foutmelding krijgt dat het bestand al bestaat kies je een andere willekeurige naam. |
There was a problem hiding this comment.
Klik op ‘Commit changes’. Als je een foutmelding krijgt dat het bestand al bestaat, kies dan een andere willekeurige naam.
|
|
||
| <!-- screenshot pull requests --> | ||
|
|
||
| 1. Klik boven in de pagina op de lichtblauwe naam van de branch die je in hebt opgegeven. |
There was a problem hiding this comment.
Dezelfde tekstuele wijzigingen als hierboven :)
|
|
||
| ## Hoe verder? | ||
|
|
||
| Nadat je pull request met veranderingen is goedgekeurd zal er op GitHub een nieuwe pull request worden aangemaakt die ervoor zorgt dat je veranderingen gepublicieerd worden naar het registry. |
There was a problem hiding this comment.
Zou hiervan maken:
Nadat je pull request met veranderingen is goedgekeurd, wordt er op GitHub een nieuwe pull request aangemaakt die ervoor zorgt dat je veranderingen worden gepubliceerd naar het registry.
WIP
Handboek ➝ Voor designers ➝ Breaking Changes