Hoppa till huvudinnehåll

Bidra till komponentbiblioteket

Att komma igång och bidra med kod till Midas är enkelt!

Du behöver​

  • En normalt fungerande WSL2 eller motsvarande setup med Node version >22.
  • Nx installerat globalt npm install --global nx@latest
npm install

Nx​

Midas är ett monorepo som hanteras med Nx. Det innebär att vi har flera olika projekt i samma repo, till exempel komponentbiblioteket, dokumentationswebben och andra verktyg. Varje projekt har sitt eget scope och kan hanteras individuellt. Du kan köra nx graph för att se en visuell representation av hur projekten är relaterade till varandra. Eftersom vissa projekt är beroende av andra, kan en ändring i ett projekt innebära att ett annat projekt också behöver en ny version. Till exempel, om theme uppdateras, så kommer components som är beroende av theme också att få en ny version.

Starta Storybook​

Storybook är ett verktyg för att bygga och visa upp UI-komponenter i en isolerad miljö. Det gör det enklare att utveckla, testa och dokumentera komponenter.

nx serve storybook

Komponentbibliotek​

Alla komponenter ligger under /packages/components och exporteras som ett npm-paket @midas-ds/components.

Tester​

  • Kör enhetstester för komponentbiblioteket, mer info finns på sidan om tester
nx test components

Dokumentationswebb​

Dokumentationswebben ligger i apps/docs och är byggd med Docusaurus.

  • Kör dokumentationen lokalt:
nx serve docs

Bygg komponentbibliotek​

Komponentbibliotek och appar kan byggas med:

nx build <namn>

och allt som byggs hamnar i /dist. Om du vill testa utanför monorepot går det att zippa med npm pack och installera i separat app med npm install [sökväg].

Arbetsflöde versionshantering​

Vi använder en enkel branchstrategi med en main-branch som alltid ska vara i ett deploybart skick. Utveckling sker i feature- eller bugfix-branchar som sedan mergas in i main. Vi använder inte develop eller andra liknande branchar för att hålla det enkelt och för att passa ett arbetssätt med kontinuerlig integration och leverans (CI/CD).

Ett exempel på hur det kan se ut i praktiken:

Branch​

Branch namnges enligt [feature|bugfix|hotfix|docs|refactor|chore|test]/[scope]/, till exempel feature/button. Scope är valfritt men om det används ska det referera till ett av projekten i monorepot, till exempel components, docs eller theme.

Commit​

Commits görs enligt conventional commits. Använd engelska, imperativ form, definiera type feat|docs|fix|refactor|test|chore|ops... för att avgöra vilken versionsändring du vill göra och scope (theme|button|etc...) som rubrik för changelog.

Se .commitlintrc.js för tillåtna types och scopes.

Våra commits är hela projektets historik, avgör vilken version nästa release blir, samt är indata till changelogs och release notes så lägg gärna en extra minut på att vara tydlig. Om du är osäker på vilken commit du ska göra, titta på conventional commits cheatsheet.

Varför conventional commits?​

  • Generera automatisk CHANGELOG
  • Automatiskt bestämma semantic version
  • Kommunicera inom team och till andra intressenter vad förändringen gäller.
  • Trigga byggen och andra åtgärder.
  • Bidra till att hålla en konsekvent och strukturerad historik.

Commit message på en rad​

docs: update button variant docs

Commit message med header och body​

fix(theme): prevent red color on button hover

Introduce new css variable to automatically
select style based on input type

Ta dig gärna tid att läsa igenom conventional commit summary och försök jobba enligt det flödet.

Innan du skapar en PR, gå igenom så att du har commits som representerar vad du har gjort. Jobbar du ensam i en feature branch och har skapat många commits? Använd git rebase -i, då kan du välja vilka commits som ska vara med och vilka som kan kombineras. Du kan också passa på att ändra commit messages.

Instruktioner för hur du använder git rebase finns här.

Bygga komponenter​

Styleguide​

Generellt, använd övriga komponenter som referens när nya läggs till. React Aria är en bra inspiration för namngivning och struktur, både via deras ostylade komponentbibliotek och via sin designsystemsimplementation React Spectrum.

  • Målet är små funktioner, små komponenter, clean code.
  • Det uppmuntras att hela tiden göra inkrementella förbättringar i kringliggande kod
  • Komponenter ska vara testbara och dokumenterade
  • Komponenter ska stödja designsystemet på ett generiskt sätt och i möjlig mån vara stateless
  • Formatera enligt Prettier standard

Importera headless-bibliotek​

Komponenter ska i första hand byggas på React Aria i den mån det går. React Aria har ett omfattande bibliotek av färdiga komponenter och hooks som går att kombinera ihop för att uppnå önskat resultat. Fördelen med att följa React Arias konventioner är att det följer med mycket gratis i form av stöd för skärmläsare, tangentbordsnavigation och olika states.

Skapa stories​

I utgångspunkt bör alla states finnas representerade som stories i Storybook. Storybook är i första hand ett internt verktyg för UX och utvecklare i designsystemet men också en publikt exponerad referens med API och visuell representation av komponenterna.

Skriv enhetstester​

Ur perspektivet att tillgänglighet är ett av designsystemets viktigaste fokusområden är det viktigt att vi regressionstestar och testar så stor del av möjliga states av alla komponenter på enhetsnivå. MIDAS använder primärt Storybook som testplattform. De stories du skapat för komponenter kan du nu använda som utgångspunkt för dina tester. Läs mer om hur vi förhåller oss till tester av våra komponenter.

Dokumentation​

Komponenten dokumenteras på dokumentationswebben med lämpliga exempel, beskrivning och properties. Normalt plockas properties upp från komponenten via react-docgen-typescript men om det har införts nya types eller interfaces kan de behöva specificeras enligt JSDoc.

Release​

Release görs med hjälp av Nx Release som räknar fram rätt version via commit messages.

Använd följande kommando:

nx release --skip-publish

eller välj vilka projekt du vill:

nx release -p components theme --skip-publish

Själva flödet är en uppdatering av changlog och package.json med ny version och en ny tagg enligt nx-project@version. Nx pushar sedan alla ändringar och taggar och berörda workflows triggas.

Behöver du skriva release notes får du commita desssa i efterhand och ompublicera dokumentationswebben, kör publish-docs-workflowet från github.

Endast Midas core-team har de nödvändiga rättigheterna för att göra nya releaser.