Bidra
Har du funnet en bug i designsystemet? Vil du legge til en ny feature, eller kanskje en helt ny komponent? Da er dette guiden for deg.
Enturs designsystem både brukes og utvikles av alle utviklere hos Entur. Vi mener at det er gjennom dette felles eierskapet vi klarer å lage et designsystem som fungerer for de som faktisk skal bruke det.
Denne guiden viser deg hvordan du kan bidra med features, bug fixes, forbedring av dokumentasjon eller tilogmed helt nye komponenter!
Hvordan sette opp utviklingsmiljøet
Først må du klone ned dette repositoryet:
$ git clone git@bitbucket.org:enturas/design-system.git
For konsistent versjonering av yarn og node, så benyttes Volta. Dette må innstalleres før du fortsetter. Les mer om innstallering av Volta her.
Gå inn i den nye mappen design-system
, og installer dependencies med yarn
:
$ yarn
Merk at vi bruker yarn
og ikke npm
i dette prosjektet. Det er fordi vi bruker en yarn-only feature - workspaces - som letter utvikling i såkalte monorepos. For å innstallere yarn
på din maskin, kjør npm install --global yarn
.
Siste steg i prosessen er å bygge alle pakkene. Dette gjør du med yarn build:packages
.
Når du har kommet hit, burde du være klar for å starte arbeidet ditt.
Scripts
Du har en rekke scripts tilgjengelig via yarn
:
Du kan starte en utviklingsversjon av dokumentasjonssiden ved å kjøre yarn start:documentation
på rotnivå. Du kan også, for en pakke, starte en byggprosess som oppdaterer seg ved endringer i koden ved å kjøre yarn start:package name
der name
er mappenavnet til pakken, f.eks: yarn start:package button
.
Alternativt kan man benytte seg av Playroom som et minimalt utviklingsmiljø hvis man ikke trenger å se endringene på dokumentasjonssiden med en gang. Les mer om Playroom her. Dette er generelt sett den anbefalte metoden for utvikling av komponenter da det sparer en god del tid.
Du kan kjøre alle testene med yarn test
og starte en test watcher med yarn test --watch
.
Du kan bygge hele prosjektet med yarn build:all
. Dette kan ta noen minutter, men kan være smart å gjøre før du lager en pull request, så ikke CI-prosessen krasjer.
Om du har de rette tilgangene, kan du også bygge og publisere nye versjoner med yarn publish
. Kun kjør denne om du har de riktige tilgangene i npm! Ellers blir det masse rot med git tags og slikt. For å få tilgang spør på #talk-admin
på Slack.
Prosjektstruktur
Designsystemet er et såkalt "monorepo". Det vil si at alle de forskjellige NPM-pakkene du laster ned finnes i samme repository. Det gjør det lettere å utvikle features på tvers av pakker, samt å samkjøre endringer som må skje i hele kodebasen.
Prosjektet er strukturert på følgende måte:
- apps/documentation
- src
- components
- gatsby-theme-docz
- utils
- content
- designprinsipper
- kom-i-gang
- ...
- packages
- package-name
- another-package-name
- ...
- bin
packages
: NPM-pakkene
packages
inneholder en mappe for hver pakke. Det vil si at @entur/typography
-pakken ligger i packages/typography
.
Om du vil utvikle på en slik pakke, kan du kjøre yarn start
i mappen til pakken for å slippe å bygge manuelt etter hver endring.
Hver av pakkene inneholder omtrentlig den samme strukturen:
- package-name
- src
- index.tsx
- ComponentName.tsx
- ComponentName.test.tsx
- ComponentName.scss
index.tsx
-filen definerer hva som kan importeres fra pakken din, og er således hoved-APIet til pakken. Derifra kan du finne frem til riktig komponent.
Vi bruker scss
til styling, og react-testing-library
og Jest for testing.
apps/documentation/content
: dokumentasjonen
All dokumentasjonen vår finner du i content
-mappa til documentation
under apps
-workspace-et. Vi har lagt dem i mapper basert på hvilken del av siden den tilhører, og hver av filene er i såkalt mdx
-format.
MDX
er Markdown med JSX-støtte i seg. Det betyr at du kan bruke React-komponenter for å lage dokumentasjonen din. Med andre ord kan du dokumentere komponenten ved hjelp av den faktiske React-komponenten. Du kan lese mer om det på dokumentasjonssiden deres.
For komponent-dokumentasjonen så har vi prøvd å standardisere utseendet og strukturen på hver side. Kopier gjerne en eksisterende fil om du skal legge til en ny side.
Frontmatter
I tillegg bruker vi noe som heter frontmatter
på toppen av hver fil, for å definere metainformasjon om hver dokumentasjonsside. Dette kan være tittelen på siden, hvilken NPM-pakke denne komponenten tilhører, hvilken rekkefølge den burde dukke opp i hvilken meny osv. Frontmatter er formatert i yaml
.
Følgende valg er tilgjengelige i frontmatter-YAMLen:
title: Tittel på siden
route: /url/til/siden
order: 1
parent: Hovedkategori (Komponenter, Kom i gang osv)
menu: Hvilken undermeny (kun relevant for komponenter-sider)
npmPackage: navnet på npm-pakken (kun relevant for komponenter-sider)
tags: søkbare, ord (kun relevant for komponenter-siden)
Det finnes et par andre også (index
, frontpage
etc), men de trenger du mest sannsynligvis aldri å bry deg om. Om i tvil, ta en titt på kildekoden.
apps/documentation/src
: dokumentasjonssiden
Trenger du å endre noe på selve dokumentasjonssiden, eller lage noen spesielle komponenter for å dokumentere noe, så kan du legge dem inn i denne mappen. Dette er nemlig koden som bygger opp selve dokumentasjonssiden!
Mappen inneholder tre mapper:
gatsby-theme-docz
inneholder toppnivå-komponentene i komponentbiblioteket.utils
inneholder utilities som brukes på kryss og tvers av sidencomponents
inneholder en rekke gjenbrukbare komponenter, som både kan brukes i dokumentasjonen og rundt om i dokumentasjonssiden.
bin
: scripts
Per i dag inneholder bin
-mappen kun ett script - new-package
-scriptet. Vi prøver å skrive alle scripts i Node, slik at det blir lettest mulig å forstå seg på.
Jeg trenger en feature eller bugfix
Start med å skrive en test for å verifisere buggen eller for å vise APIet til den nye featuren din. Det gjør det enklere for deg å utvikle, og for de som skal verifisere pull requestet ditt å forstå hva du har gjort.
Neste steg er å faktisk skrive koden som fikser bugen eller implementererer featuren. Sjekk at testen passerer!
Det kan jo være greit å se en versjon av komponenten din mens du utvikler.
Du kan starte opp en dev-versjon av dokumentasjonssiden med yarn start:documentation
på rotnivå, og en lokal file watcher som rekompilerer filene dine med yarn start
i mappen der pakken du jobber på ligger.
Så om du utvikler en komponent for @entur/a11y
-pakken, gjør du følgende:
$ ~/design-system: yarn start:documentation
# så, i en annen terminal
$ ~/design-system: cd packages/a11y
$ ~/design-system/packages/a11y: yarn start
Så går du til dokumentasjonssiden for den featuren du jobber på, og ser at alt oppfører seg som forventet. Du kan tweake på komponenten så mye du vil i en Playground, eller bare rendre den rett i dokumentet.
Mens vi snakker om dokumentasjon - trenger du å dokumentere endringen din? Neste steg er i så fall å legge til eller endre det som skal til på dokumentasjonssiden. Dokumentér heller for mye enn for lite!
Til slutt committer du endringen din med git commit …
eller yarn gc:format
. Vi bruker et verktøy som heter commitizen
for å standardisere commit-meldinger.
commitizen
aktiveres automatisk hvis du er i master
-branch-en og kan ellers aktiveres med yarn gc:format
(«gc» står for git commit).
Følg brukergrensesnittet så godt du kan, så burde du komme ganske godt i mål.
Når den spør om "scope", skriv opp navne(t|ne) på komponenten(e) du har endret, eller bare hopp over.
Ved push av endrigene dine vil en commit-linter sjekke om du har fulgt conventional-commits
-stilen. Ved bruk av yarn gc:format
sikrer du at
du alltid følger denne konvensjonen.
Playroom
Hvis man vil spare tid på utviklingsprosessen, så benyttes også (Playroom)[https://github.com/seek-oss/playroom] som et alternativ for utvikling og videreutvikling.
Opprett filen TestBench.tsx
under apps/code-playground/src
. Innholdet i denne filen vil vises i et minimalt miljø når man kjører yarn start:code-playground
. Denne filen trackes ikke av git, og vil og skal dermed ikke oppdateres i git-historikken.
Playroom tillater også å gjøre kodeendringer rett i nettleseren, men for ekstra Typescript-støtte o.l. så er endringer direkte i TestBench
anbefalt
import React from 'react';
export const TestBench = () => {
return <div>{/* Komponenter man ønsker å teste her */}</div>;
};
Merk: TestBench.tsx
er lagt til i .gitignore
og vil derfor aldri være inkludert i git-historikken.
Jeg vil legge til en ny pakke
Da kan du kjøre yarn new-package
, og så vil du bli guidet gjennom valg av navn, og en liste med manuelle steg du enn så lenge må gjøre.
Husk å diskuter dette på #talk-designsystem
-kanalen før du kjører i gang - så vi kan bli enige om at det er riktig ting å gjøre.
Jira og retningslinjer
Vi har en Jira-tavle for å opprette oppgaver. Vi anbefaler at du oppretter en Jira-sak på det arbeidet du skal gjøre, slik at vi får muligheten til å tallfeste hvor mange slike saker vi går gjennom, samt å ha en bedre historikk enn det vi kan få gjennom Git alene.
Du vil finne retningslinjer for bruk for komponentene på sidene til hver enkelt komponent.
Felles ansvar
Selv om dette er et distribuert prosjekt på tvers av Entur sine mange utviklingsteam, er det et kjerneteam som "eier" selve designsystemet. Det er ledet av Long Ngo (design) og Magnus Rand (utvikling). Det er ikke tenkt at de skal "gjøre alt arbeidet", men de vil være tilretteleggere for samarbeid på tvers av organisasjonen.
Spørsmål?
Sitter du fast? Lurer du på noe? Har du lyst til å slå av en hyggelig prat?
Da kan du stikke innom #talk-designsystem
-kanalen vår på Slack. Der vil du finne mange som enten jobber med designsystemet hver dag, eller som kanskje vet hvem du kan spørre.