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
.
To get Yarn installed, you need to setup a default version of Node, run these commands:
volta install node
volta install yarn
- Register your Docker account on Hub-Docker
- Download Docker app locally on your machine and login
- Start Docker
- Clone
porsche-design-system
repository - Switch to project root directory
- Checkout branch main by executing
git checkout main
- 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
) - Make sure that Docker app is running
- Create a personal access token with the scope
repo
at https://github.com/settings/tokens - Add the personal access token to the
.env
file in following formatGITHUB_PERSONAL_ACCESS_TOKEN=YOUR_TOKEN
- 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
- 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 - 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
Error: spawn node-gyp ENOENT
=> You need to installnode-gyp
manually viayarn global add node-gyp
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.
- Go to Webstorm
Preferences
- Click on the Plugins tab and search for
prettier
- Install prettier
- In
Preferences
go toLanguages and Frameworks
->Javascript
->Prettier
- Set
Prettier Package
to{PATH_TO_YOUR_DIRECTORY}/node_modules/prettier
- Change
Run for files
to{**/*,*}.{js,ts,jsx,tsx,vue,scss,json,css,html,md}
- Click checkbox
on save
and apply - You should be good to go.
- If you have to exclude code fom being prettified, see Prettier configuration
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-build
(builds the entire application)./docker.sh run-build --assets
(builds the assets with icons, fonts and marque)./docker.sh run-build --components
(builds the native stencil web components)./docker.sh run-build --components-prod
(builds the native stencil production web components)./docker.sh run-build --components-js
(builds the native web components)./docker.sh run-build --components-js-prod
(builds the native production web components)./docker.sh run-build --components-angular
(builds angular components)./docker.sh run-build --components-react
(builds react components)./docker.sh run-build --core-dependencies
(builds utilities, icons, fonts, marque and assets)./docker.sh run-build --fonts
(builds the font set)./docker.sh run-build --icons
(builds the optimized icon set)./docker.sh run-build --marque
(builds the marque)./docker.sh run-build --partials
(builds the partials)./docker.sh run-build --storefront
(builds storefront)./docker.sh run-build --utilities
(builds utilities)
Important: before executing a start command it's necessary to have ./docker.sh run-build
executed.
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-start
(starts storefront as default)./docker.sh run-start --components
./docker.sh run-start --components-js
./docker.sh run-start --components-angular
./docker.sh run-start --components-react
./docker.sh run-start --storefront
./docker.sh run-start --utilities
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-lint
(lints the entire application)./docker.sh run-lint --components-js
(lints native web components)./docker.sh run-lint --storefront
(lints storefront)
- Switch to project root directory
- Run
./docker.sh run-test
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-test-unit
(unit tests for the entire application)./docker.sh run-test-unit --components-js
(unit tests for the native web components)./docker.sh run-test-unit --components-react
(unit tests for the generated react wrappers)./docker.sh run-test-unit --storefront
(unit tests for the storefront)./docker.sh run-test-unit --utilities
(unit tests for the utilities)
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-test-mocks
(mock tests for the entire application)./docker.sh run-test-mocks --components-react
(mock tests for the react components)
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-test-e2e
(e2e tests for the entire application)./docker.sh run-test-e2e --components-js
(e2e tests for the native web components)./docker.sh run-test-e2e --components-angular
(e2e tests for angular components)./docker.sh run-test-e2e --components-react
(e2e tests for react components)./docker.sh run-test-e2e --components-vue
(e2e tests for vue components)./docker.sh run-test-e2e --crawler
(e2e tests for crawler package)./docker.sh run-test-e2e --storefront
(e2e tests for the storefront)
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-test-vrt --components-js
(executes all vrt tests in Chromium and WebKit)./docker.sh run-test-vrt --components-js --grep multi-select
(executes e.g. all "Multi Select" related vrt tests in Chromium and WebKit)yarn test:vrt:components-js --ui
(launches UI Mode of Playwright, – not possible within Docker context but perhaps still helpful for debugging purposes)./docker.sh run-test-vrt --components-js:chrome
(executes all vrt tests in Chromium)./docker.sh run-test-vrt --components-js:chrome:common
(executes all "common" vrt tests in Chromium)./docker.sh run-test-vrt --components-js:chrome:custom
(executes all "custom" vrt tests in Chromium)./docker.sh run-test-vrt --components-js:chrome:states
(executes all "states" vrt tests in Chromium)./docker.sh run-test-vrt --components-js:safari
(executes all vrt tests in WebKit)
./docker.sh run-test-vrt --components-angular
(vrt tests for angular components)./docker.sh run-test-vrt --components-react
(vrt tests for react components)./docker.sh run-test-vrt --components-react/nextjs
(vrt tests for react ssr components in nextjs setup)./docker.sh run-test-vrt --components-react/remix
(vrt tests for react ssr components in remix setup)./docker.sh run-test-vrt --components-vue
(vrt tests for vue components)./docker.sh run-test-vrt --storefront
(vrt tests for the storefront)./docker.sh run-test-vrt --utilities
(vrt tests for the utilities)./docker.sh run-test-vrt --fallbacks
(vrt tests for the fallbacks)
- Switch to your results directory in
/packages/{DESIRED_PACKAGE_NAME}/tests/vrt/results
. Here you can find the belongingdiff
andregression
images. - Check if you would like to accept the changes
- If yes: Replace the reference shot in the
/vrt/fixtures
folder with the belonging one in the/vrt/results
folder and delete the images in the/vrt/results
directory afterwards manually. - If no: Recheck your code and run the tests again, when you think you fixed it.
Note: In most of the cases this test only make sense to be executed in CI/CD
- Switch to project root directory
- For the different applications, select one of the following commands:
./docker.sh run-test-smoke --components-js
(smoke tests for the native web components)./docker.sh run-test-smoke --components-react
(smoke tests for the React components based on web components)./docker.sh run-test-smoke --components-vue
(smoke tests for the Vue components based on web components)
- 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. changev1.39.0-focal
tov1.39.0-focal-test
(not doing this will essentially replace the previous image that is used everywhere else) - Commit and push your changes
- Go to Build and Push Docker Image workflow
- Hit the
Run workflow
button on the right, choose the branch with your changes and clickRun workflow
CTA button to queue a manual build - Once the job is complete, you can verify the new image at GitHub-Packages Page
- Now you can rerun your regular CI job (since it failed due to relying on the not yet existing docker image)
Every week, we update our NPM packages:
- Switch to project root directory
- 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. - Angular has to be updated with
ng update
. - Run
./docker.sh bash
cd packages/components-angular
./node_modules/.bin/ng update
./node_modules/.bin/ng update @angular/cli @angular/core
- Check
MAX_TS_VERSION
inpackages/components-angular/node_modules/@angular/compiler-cli/src/typescript_support.js
which indicates whethertypescript
can be updated for Angular packages or not. exit
to leave the docker container- Run
./docker.sh run-install
- Run
./docker.sh run-build
- Run
./docker.sh run-test
As final check start application locally and have a look at it. - Run
./docker.sh run-start
- Make sure you pulled the latest version before starting.
- To avoid corrupting the
yarn.lock
start with Angular (by usingng update
). The following upgrades should be grouped e.g. if React types can be upgraded also look if React can be upgraded. - Don't upgrade too many dependencies at once, keep them logically together.
- Certain dependencies can not be upgraded which are documented in
docs/dependencies.md
- 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
- Update
docs/dependencies.md
to reflect the current date and adjust framework versions if needed - Once you updated everything possible, delete
yarn.lock
and have it created again by runningyarn
in order to update dependencies of our dependencies
This tool automatically creates a catalog of ui components. For its magic to work, new components have to follow a few rules:
- File location: A component is developed as a self containing element under
packages/components/src/components
. - Component description: A component should have a
COMPONENTNAME.code.md
and aCOMPONENTNAME.design.md
file which describes its general purpose, design/development specifications and examples. - Props: The component has to describe its props using typescript types and documentation.
In order to deploy something to AWS from your local machine, you need to follow these steps.
- Install
awscli
as described here https://docs.aws.amazon.com/cli/latest/userguide/install-cliv2-linux.html#cliv2-linux-install - Retrieve the credentials from our keepass, they are stored in the entry
AWS + QuickSight
under the fieldsZugriffsschlüssel-ID
andGeheimer Zugriffsschlüssel
- Run
aws configure
and enter the credentials, default regioneu-central-1
and default output formatjson
- If you prefer to run commands via
docker.sh
you need to extend your.env
file byAWS_ACCESS_KEY_ID
andAWS_SECRET_ACCESS_KEY
with the credentials from the previous step
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.
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.
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.
- Switch to project root directory
- Run
git pull origin {main- or v-branch}
- Create a new branch e.g. release/components-v1.2.3
- 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)
./packages/components/CHANGELOG.md
- 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.)
- 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}
- Push the local commit to release branch, e.g.
git push origin release/components-v1.2.3
- Create pull request and start review
- Merge into main- or v-branch branch (then CI/CD will trigger a release automatically)
- Go to according examples Projects:
- https://github.com/porsche-design-system/sample-integration-angular
- https://github.com/porsche-design-system/sample-integration-react
- https://github.com/porsche-design-system/sample-integration-nextjs
- https://github.com/porsche-design-system/sample-integration-vanillajs
- Run
yarn upgrade-interactive
and upgrade@porsche-design-system/components-(js/react/angular)
version. - Run
yarn
- Run
yarn build
- Run
yarn start
and check if everything works.
- Write a Slack notification by coping last entry of
./packages/components-js/CHANGELOG.md
in public Porsche Design System Slack channel
- Copy new Icon-file (eg.
newIcon.svg
) to the correct category "./packages/icons/src/CHOOSE_RIGHT_CATEGORY" - Release Assets
@porsche-design-system/assets
(see below)
- Switch to project root directory
- Run
git pull origin {main- or v-branch}
- Create a new branch e.g. release/assets-v1.2.3
- Make sure all relevant changes for the new release to be documented in following
CHANGELOG.md
file(s) under section [Unreleased]
./packages/assets/CHANGELOG.md
- 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.)
- Create a commit with following message structure
Release Porsche Design System - Assets v{MAJOR_NUMBER}.{MINOR_NUMBER}.{PATCH_NUMBER} | {DEVELOPER_ABBREVEATION}
- Push the local commit to release branch, e.g.
git push origin release/assets-v1.2.3
- Create pull request and start review
- Merge into main- or v-branch branch (then CI/CD will trigger a release automatically)
- For the moment it's treated as silent release, so no communication is required