Hvordan forholder vi oss til “total lansering” av bidrag i Jøkul?

[onordbo]

🥴 TOO LONG WON'T READ: Vi har behov for felles samle-oppgaver med noen krav til hva vi som designere og utviklere synes skal være på plass for å lansere eller endre noe i Jøkul, og gjøre det enklere for alle å vite hva som må gjøres, og hvordan.

📣 Bakteppe

Det pågår en del strukturering og dokumentasjon i Jøkul for tiden. Vi har laget nye portalsider, det kommer mer og mer dokumentasjon av komponenter på plass, og Figma blir gjennomgått med finkam for å sørge for at vi er konsekvente i måten vi dokumenterer biblioteket og setter sammen komponenter på. I løpet av denne tiden har jeg vært med på å lage nye ting til Jøkul, og jeg har observert fra sidelinjen hvordan andre forholder seg til nye bidrag.

Jeg synes vi har en ganske god struktur på plass, men jeg synes ikke den er så godt dokumentert. På utviklersiden finnes det litt mer rammebetingelser ettersom verktøyene har tilrettelagt for dette ganske lenge, og det er god innarbeidet. Når det er sagt så foreligger det mye uforløst potensiale på designsiden av bidrag til Jøkul. Versjonskontroll og "par-designing" med reviews er nok et relativt nytt konsept for mange av oss, og jeg tror at vi kan tjene mye på å samle oss rundt en felles enighet om hvordan vi jobber med dette, på tvers av design og utvikling.

🤔 Utfordring

Det har (frem til nylig) ikke eksistert en dokumentert forklaring på hvordan vi går frem for å lansere bidrag i designsystemet. På design-siden har det frem til nå vært ganske fritt fram, så lenge man vet litt hvordan Figma fungerer, dette har sin naturlige årsak i at Figma ikke har hatt mye funksjoner som støtter strukturerte bidrag frem til nylig.

Konsekvensen av dette er et bibliotek som har spredning i hvordan vi dokumenterer komponentene våre, og manglende dokumentasjon i kode og portalen. Det kan potensielt føre til mangler i systemer og misforståelser blant mennesker, og eventuelt mindre bidrag og bruk av designsystemet.

I dag har vi to forskjellige "arbeidsstrømmer" for å lansere nye bidrag i Jøkul:

• For kode: Pull Requests (og issues) på GitHub opprettes og jobbes gjennom med sjekklister
• For design: "Fristil" rett i Figma-biblioteket eller byggesonen. (Branches og Merge Requests er tilgjengelig, men ikke brukt av alle enda siden det er såpass nytt)

Hvordan samler vi dette sammen på tvers av fagdisipliner? Når regner vi bidrag som helt lansert? Hva er minstekravene for godkjenning/lansering av de forskjellige arbeidsstrømmene? Hvis en av kjerneverdiene i organisasjonen vår er at vi skal gjøre ting sammen, er dette spørsmål jeg tror det er lurt at vi reflekterer rundt, og besvarer i fellesskap.

💡 Løsningsforslag

Siden vi er mange som jobber med Jøkul fra vidt forskjellige teams, så har vi over tid flyttet mer og mer stæsj inn i GitHub. Dette gjør at vi kan samles rundt samme sted når vi skal forholde oss til designsystemet, akkurat som leveranseteamene har sine områder (Jira/Confluence/etc) for å forholde seg til sine prosjekter.

For dere som har tatt kurset vårt, så vet vi at i GitHub heter oppgaver "Issues". I utviklerverdenen kan Pull-Requests kan linkes til Issues, og vi vet at Figma filer kan embeddes i GitHub (med en utvidelse av nettleseren).

Burde ett “totalbidrag” stamme fra et Issue?

I mitt hode burde vi kunne samle arbeid fra både utvikling og design på samme sted, slik at vi som team kan avstemme bidrag i fellesskap, før de lanseres. Jeg foreslår at vi bruker Issues som en slags "Mega Pull Request" for både design og utvikling, en slags superoppgave, eller epic for de som kommer fra en Jira-liknende verden.

Disse superoppgavene burde ha noen grunnleggende føringer som vi alle må forholde oss til, slik at vi leverer inn konsistente bidrag til Jøkul. Jeg har et par ideer til hva som burde inngå:

• En beskrivelse på et par setninger av hva bidraget gjelder, og eventuelt en lenke til en diskusjon med mer informasjon
• En lenke fra Figma (direkte til branchen som bidragsarbeidet gjennomføres på)
• En lenket pull-request til koden som gjelder for bidraget
• En sjekkliste med huskereglene fra portalen

For å kunne lukke en superoppgave og regne et bidrag som lansert, foreslår jeg følgende:

• En branch fra Figma må være godkjent og merget i henhold til gjeldende forutsetninger
• En pull-request med kode burde være godkjent og merget i henhold til gjeldende forutsetninger

[onordbo]

Slik jeg ser det så er det et par ting som må på plass for at vi skal kunne formalisere denne delen av nye bidrag.

• Man burde enkelt kunne opprette en "Mega Pull Request" (Er bidrags-issue et bedre navn? eller kanskje bare bidrag? eller idé? Tar gjerne noen innspill her) på GitHub fra en mal som hjelper til å komme i gang
• Man burde kunne lese om hvordan man bidrar til Jøkul
  • Portalen for å forklare helheten
  • Figma for ekstra designer-stæsj
  • GitHub for ekstra utvikler-stæsj
• Man burde ha en sjekkliste å forholde seg til som tipser om alt som må gjøres underveis
  • Utviklere har en liten sjekkliste på PR's, skal vi hente noe derifra, eller legge til noe ekstra i bidrags-issues?
  • Designere har ingenting etablert fra før, men dette ligger nå i portalen og i det nye onboarding forslagt i Figma

Her er mitt første take på en issue-mal for nye bidrag 👇

---

<Tittel på nytt bidrag>

<!--
Oppsummer kort hva du ønsker å gjøre.
Designet trenger ikke være ferdig, men det må
være en aktivitet knyttet til dette issuet – enten
design, utvikling, eller begge deler. Hvis du har
kontekst fra en tidligere diskusjon på GitHub,
legg ved lenken til den som vist ovenfor.
https://github.com/fremtind/jokul/discussions
-->

Discussion: Legg inn fra https://github.com/fremtind/jokul/discussions
Pull-request: Legg inn lenke til GitHub pull-request
Designskisser: Legg inn lenke til Figma-branch

🎯 Sjekkliste for nye bidrag

Denne listen er hentet fra portalen. Den skal sørge for at alle som bidrar har gode forutsetninger for å gjøre designsystemet bedre for alle, og at alt av nødvendig dokumentasjon blir ivaretatt underveis.

🤝 For alle ansvarlige assignees

• Jeg har dokumentert endringen i portalen med formål, et interaktivt eksempel, prinsipper for riktig og feil bruk, eksempel på live kode og tilgjengelige react props.
• Jeg har sjekket at relevant dokumentasjon for design og utvikling er på plass i sine respektive fagområder

🎨 For designere

• Jeg har ferdigstilt designet mitt i en branch av biblioteket
• Jeg har sjekket at nødvendige auto-layout regler og variants fungerer
• Jeg har laget relevant dokumentasjon i Figma i tråd med resten av biblioteket
• Jeg har fått arbeidet sjekket av minst en annen designer/utvikler
• Jeg har fått godkjent merge-requesten min via kjerneteamet

🤖 For utviklere

• Jeg har dokumentert koden på GitHub
• Jeg har kjørt nødvendige tester og de har passert
• Andre utviklere har godkjent koden i en pull-request

🌈 Bonuspoeng

• Jeg har skrevet kontrollspørsmål for bruk av komponenten
• Jeg har lagt til eksempler på bruk ute fra leveranseteamene
• Jeg har referert til andre relevante komponenter ved behov

[onordbo]

Har skrudd litt på språket, men ellers er det stort sett det samme som du foreslo @wkillerud. Ser nå i etterkant av å ha lest denne teksten et par ganger, at det ser ut som vi mangler et sted som lister ut minstekravene for dokumentasjon for de respektive fagområdene. Utenom huskelista, som imo er litt for generell til å dekke det man burde vite, om man er "uindoktrinert" i dokumentasjonsbehovet for sitt fagområde.

Det er kanskje en tråd for seg selv; men hvor burde slike spesifikke lister leve? Initielt tenker jeg det burde være i fagsystemene, så vi ikke gjør huskelista "for alle" unødvendig lang. Anywho, her er det ferskeste forslaget på ny issue mal.

👈 Ny issue-mal 2022 👇

< Tittel >

<!-- Oppsummer kort hva som skal gjøres -->

Discussion: Legg inn fra https://github.com/fremtind/jokul/discussions
Pull request: Legg inn lenke til GitHub pull-request når den er klar
Designskisser: Legg inn lenke til Figma-branch når den er klar

🎯 Sjekkliste

Gjør deg kjent med huskelista for nye bidrag, i tillegg til minstekravene for dokumentasjon i portalen, Figma, og i readme på GitHub.

🎨 For designere

• Laget et forslag inkludert dokumentasjon i en egen branch i Figma-biblioteket, og åpnet en merge request
• Sjekket at auto-layout regler, animasjoner og variants fungerer som de skal
• Merge request er blitt godkjent

🧑‍💻 For utviklere

• Laget et forslag inkludert dokumentasjon på en egen branch, og åpnet en pull request
• Testet responsivitet og UU (tastaturnavigasjon, skjermleser)
• Pull request er blitt godkjent

For ekstra ✨bonuspoeng✨ legger du ved eksempler på bruk, referanser til andre relevante komponenter og skriver et par kontrollspørsmål for bruk.

[wkillerud]

For GitHub kan en sånn spesifik liste fint leve i https://github.com/fremtind/jokul/blob/main/CONTRIBUTING.md, med en henvisning dit fra malen både for issues og pull requests egentlig.

[onordbo]

Agree, for Figma tenker jeg at vi kan bygge ut introduksjonen med en ekstra side for å dekke det nødvendige, da konteksten allerede er på plass der.

https://www.figma.com/file/y9JtTf3whfTCHCdYSUXVQ5/?node-id=2396%3A6296

[onordbo]

@wkillerud: Jeg foreslår at vi lanserer ny issue mal uten spesifikke lister, for å unngå forsinkelser pga bakslep på detaljer. Skal vi modde språket for å si at det kommer, eller la det stå som det er?

[wkillerud]

Jeg foreslår at vi lanserer ny issue mal uten spesifikke lister, for å unngå forsinkelser pga bakslep på detaljer. Skal vi modde språket for å si at det kommer, eller la det stå som det er?

Vet ikke om jeg forstår hva du mener 😅 In any case, laget #2665 så vi kan ta detaljer der.