Home

Awesome

Porsche Design System

Build status

Actions Status

Setup

Install Volta

We recommend using Volta to manage the correct Node and Yarn version. To get started, install Volta like this:

curl https://get.volta.sh | bash

Volta should automatically pick up the correct Node and Yarn version set in package.json.

Install Node & Yarn

To get Yarn installed, you need to setup a default version of Node, run these commands:

volta install node
volta install yarn

Install Docker

  1. Register your Docker account on Hub-Docker
  2. Download Docker app locally on your machine and login
  3. Start Docker

Getting started

  1. Clone porsche-design-system repository
  2. Switch to project root directory
  3. Checkout branch main by executing git checkout main
  4. Create an .env file within project root directory (never push this file to Git because it will contain secrets – by default it's ignored by .gitignore)
  5. Make sure that Docker app is running
  6. Create a personal access token with the scope repo at https://github.com/settings/tokens
  7. Add the personal access token to the .env file in following format GITHUB_PERSONAL_ACCESS_TOKEN=YOUR_TOKEN
  8. Login to the GitHub docker registry via grep GITHUB_PERSONAL_ACCESS_TOKEN .env | cut -d '=' -f2 | docker login https://ghcr.io -u YOUR_USERNAME --password-stdin
  9. Run ./docker.sh run-install (to have npm dependencies installed within Docker container) - this may take up to several minutes at first start depending on your internet connection
  10. Run yarn (to have npm dependencies installed on your machine for better IDE support) - this may take up to several minutes at first start depending on your internet connection

Common errors during installation

  1. Error: spawn node-gyp ENOENT => You need to install node-gyp manually via yarn global add node-gyp
  2. node-pre-gyp ERR! install response status 404 Not Found on https://github.com/Automattic/node-canvas/releases/download/v2.11.2/canvas-v2.11.2-node-v108-darwin-unknown-arm64.tar.gz => Check out this page

Note: ./docker.sh run-install and yarn should be executed after every pull.

Setup Prettier (Formatter)

  1. Go to Webstorm Preferences
  2. In Preferences go to Languages and Frameworks -> Javascript -> Prettier
  3. Activate Automatic Prettier configuration
  4. Change Run for files to {**/*,*}.{md}
  5. Click checkbox Run on save and apply
  6. You should be good to go.
  7. If you have to exclude code fom being prettified, see Prettier configuration

Setup Biome (Formatter + Linter)

  1. Go to Webstorm Preferences
  2. Click on the Plugins tab and search for biome
  3. Install Biome
  4. In Preferences go to Languages and Frameworks -> Biome
  5. Activate Automatic Biome configuration
  6. Change Run for files to **/*.{js,mjs,cjs,ts,jsx,tsx,cts,json,jsonc,vue,svelte,astro,css}
  7. Click checkbox Run format on save + Run safe fixes on save and apply
  8. You should be good to go.
  9. If you have to exclude code fom being prettified, see Biome configuration

Build

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

Start

Important: before executing a start command it's necessary to have ./docker.sh run-build executed.

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

Linting

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

All Tests

  1. Switch to project root directory
  2. Run ./docker.sh run-test

Unit Tests

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

Mock Tests

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

E2E Tests

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

Visual Regression Tests

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

What to do when VRT tests are failing

  1. Switch to your results directory in /packages/{DESIRED_PACKAGE_NAME}/tests/vrt/results. Here you can find the belonging diff and regression images.
  2. Check if you would like to accept the changes

Smoke Tests

Note: In most of the cases this test only make sense to be executed in CI/CD

  1. Switch to project root directory
  2. For the different applications, select one of the following commands:

Docker

What to do after adjusting docker scripts

  1. Bump the docker image tag everywhere except for the first layer of our Dockerfile (e.g. FROM mcr.microsoft.com/playwright:v1.39.0-focal needs to stay) to not break all CI runs of your colleagues, e.g. change v1.39.0-focal to v1.39.0-focal-test (not doing this will essentially replace the previous image that is used everywhere else)
  2. Commit and push your changes
  3. Go to Build and Push Docker Image workflow
  4. Hit the Run workflow button on the right, choose the branch with your changes and click Run workflow CTA button to queue a manual build
  5. Once the job is complete, you can verify the new image at GitHub-Packages Page
  6. Now you can rerun your regular CI job (since it failed due to relying on the not yet existing docker image)

Dependency updates

Every week, we update our NPM packages:

  1. Switch to project root directory
  2. Run ./docker.sh run-upgrade
    This should output the dependencies you might want to update. Select the NPM dependencies to be updated and press _ Enter_. Afterwards execute automated tests to make sure application still works.
  3. Angular has to be updated with ng update.
  4. Run ./docker.sh bash
  5. cd packages/components-angular
  6. ./node_modules/.bin/ng update
  7. ./node_modules/.bin/ng update @angular/cli @angular/core
  8. Check MAX_TS_VERSION in packages/components-angular/node_modules/@angular/compiler-cli/src/typescript_support.js which indicates whether typescript can be updated for Angular packages or not.
  9. exit to leave the docker container
  10. Run ./docker.sh run-install
  11. Run ./docker.sh run-build
  12. Run ./docker.sh run-test
    As final check start application locally and have a look at it.
  13. Run ./docker.sh run-start

Hints for updating

  1. Make sure you pulled the latest version before starting.
  2. To avoid corrupting the yarn.lock start with Angular (by using ng update). The following upgrades should be grouped e.g. if React types can be upgraded also look if React can be upgraded.
  3. Don't upgrade too many dependencies at once, keep them logically together.
  4. Certain dependencies can not be upgraded which are documented in docs/dependencies.md
  5. In case you discover new dependencies that can not be upgraded, e.g. due to esm builds not compatible with nodejs, add them to the list
  6. Update docs/dependencies.md to reflect the current date and adjust framework versions if needed
  7. Once you updated everything possible, delete yarn.lock and have it created again by running yarn in order to update dependencies of our dependencies

Build status

GitHub Actions

Developing new components

This tool automatically creates a catalog of ui components. For its magic to work, new components have to follow a few rules:

  1. File location: A component is developed as a self containing element under packages/components/src/components.
  2. Component description: A component should have a COMPONENTNAME.code.md and a COMPONENTNAME.design.md file which describes its general purpose, design/development specifications and examples.
  3. Props: The component has to describe its props using typescript types and documentation.

Open Source Check via OSS Review Toolkit (ORT) by Porsche's Open Source Office (OSO)

The OSS Review Toolkit (ORT) aims to assist with the tasks that commonly needs to be performed in the context of license compliance checks, especially for Free and Open Source Software dependencies.

When should the ORT - Analyzer be running?

A zipped ORT analysis file, analyzer-result.yml, is generated on every first day of month and is sent by GitHub Actions to OSO automatically.

Where can I check FOSS status report?

OSO service desk

Where can I access the list of licenses which can be used in product development lifecycle?

Porsche License List

Release management

Porsche Design System - Components (JS/Angular/React)

Note

When publishing a stable release then it's necessary an RC release is made immediately before, integrated and tested in all sample integration projects. The stable release needs to be exactly the same as the RC release to make sure everything works under real conditions.

Preparation

  1. Switch to project root directory
  2. Run git pull origin {main- or v-branch}
  3. Create a new branch e.g. release/components-v1.2.3
  4. Make sure all relevant changes for the new release to be documented in following CHANGELOG.md file(s) under section [Unreleased] (this file will also be used to show on Storefront)
  1. Run ./docker.sh run-prepare-release-components ${TARGET_VERSION} (If something goes wrong, make sure to revert all local changes before executing the task again.)

Release

Stable

  1. Create a commit with following message structure Release Porsche Design System - Components (JS/Angular/React/Vue) v{MAJOR_NUMBER}.{MINOR_NUMBER}.{PATCH_NUMBER} | {DEVELOPER_ABBREVEATION}
  2. Push the local commit to release branch, e.g. git push origin release/components-v1.2.3
  3. Create pull request and start review
  4. Merge into main- or v-branch branch (then CI/CD will trigger a release automatically)

Update sample projects

  1. Go to according examples Projects:
  1. Run yarn upgrade-interactive and upgrade @porsche-design-system/components-(js/react/angular) version.
  2. Run yarn
  3. Run yarn build
  4. Run yarn start and check if everything works.

Communicate

  1. Write a Slack notification by coping last entry of ./packages/components-js/CHANGELOG.md in public Porsche Design System Slack channel

Porsche Design System - New Icons

  1. Copy new Icon-file (eg. newIcon.svg) to the correct category "./packages/icons/src/CHOOSE_RIGHT_CATEGORY"
  2. Release Assets @porsche-design-system/assets (see below)

Porsche Design System - Assets

Preparation

  1. Switch to project root directory
  2. Run git pull origin {main- or v-branch}
  3. Create a new branch e.g. release/assets-v1.2.3
  4. Make sure all relevant changes for the new release to be documented in following CHANGELOG.md file(s) under section [Unreleased]
  1. Run ./docker.sh run-prepare-release-assets ${TARGET_VERSION} (If something goes wrong, make sure to revert all local changes before executing the task again.)

Release

  1. Create a commit with following message structure Release Porsche Design System - Assets v{MAJOR_NUMBER}.{MINOR_NUMBER}.{PATCH_NUMBER} | {DEVELOPER_ABBREVEATION}
  2. Push the local commit to release branch, e.g. git push origin release/assets-v1.2.3
  3. Create pull request and start review
  4. Merge into main- or v-branch branch (then CI/CD will trigger a release automatically)

Communicate

  1. For the moment it's treated as silent release, so no communication is required