Skip to content

Latest commit

 

History

History
381 lines (263 loc) · 8.21 KB

DEVELOPMENT.md

File metadata and controls

381 lines (263 loc) · 8.21 KB
Raw

Development

This document describes the process for running this project on your local computer, and the list of steps to perform when creating a new major or minor version branch of the monorepo.

Getting started

Setup the repo:

yarn

Start the development server:

yarn start

Linting

Run all the code style checks:

yarn lint

Run ESLint and Prettier checks:

yarn lint:js

Run Stylelint to check themes:

yarn lint:css

Run TypeScript to check typings:

yarn lint:types

Testing

Environment variables

Setup the environment variables needed by the scripts below, by copying the .env.dist template file to .env:

cp .env.dist .env

and then configure the individual variable values in the newly created .env file.

Not all variables are necessary for all scripts, individual sections below will note which variables are required to run a command.

Unit tests

Run tests in Chrome:

yarn test

Run tests in Firefox:

yarn test:firefox

Run tests in WebKit:

yarn test:webkit

By default, tests will only run for changed packages. To run tests for all packages, use the --all flag:

yarn test --all

Run tests for single package:

yarn test --group combo-box

Debug tests for single package:

yarn debug --group combo-box

Run or debug specific test files filtered by a glob pattern:

yarn test --group combo-box --glob="data-provider*" # all data provider tests
yarn test --group combo-box --glob="*polymer.test.js" # all polymer tests
yarn test --group combo-box --glob="*lit.test.js" # all lit tests

yarn debug --group combo-box --glob="data-provider*" # all data provider tests
yarn debug --group combo-box --glob="*polymer.test.js" # all polymer tests
yarn debug --group combo-box --glob="*lit.test.js" # all lit tests

Run tests with code coverage:

yarn test --coverage

Visual tests

To run the visual tests, please make sure that the SAUCE_USERNAME and SAUCE_ACCESS_KEY environment variables are defined.

Run tests for Lumo:

yarn test:lumo

Run tests for Material:

yarn test:material

Update reference screenshots for Lumo:

yarn update:lumo

Update reference screenshots for Material:

yarn update:material

Update screenshots for single package:

yarn update:lumo --group combo-box

Snapshot tests

Run snapshot tests that are in test/dom folders under components:

yarn test:snapshots

Update snapshots for all components that have corresponding tests:

yarn update:snapshots

Update snapshots for single package:

yarn update:snapshots --group combo-box

Integration tests

Run integration tests that are in the separate integration folder:

yarn test:it

Making a version bump

Create a branch for the current major

Checkout main and pull latest changes:

git checkout main && git pull

Create a new branch from main:

git checkout -b 24.0

Push a newly created branch:

git push origin 24.0

The newly created branch for the current major is protected by default. The rest of the changes to that branch should happen the usual way, through a PR.

Create another branch:

git checkout -b update-v24.0

Update wtr-utils.js as follows:

const isLockfileChanged = () => {
-  const log = execSync('git diff --name-only origin/main HEAD').toString();
+  const log = execSync('git diff --name-only origin/24.0 HEAD').toString();
  return log.split('\n').some((line) => line.includes('yarn.lock'));
};
const getChangedPackages = () => {
-  const output = execSync('./node_modules/.bin/lerna ls --since origin/main --json --loglevel silent');
+  const output = execSync('./node_modules/.bin/lerna ls --since origin/24.0 --json --loglevel silent');
  return JSON.parse(output.toString());
};

Create a PR to the version branch (example).

Update the version in main

Create a new branch from main:

git checkout main && git checkout -b bump-v24.1

Prepare a new version for the updateVersion script by running the following command:

export npm_config_bump=24.1.0-alpha0

Run the script to bump static version getters in ElementMixin, Lumo and Material:

node scripts/updateVersion.js

Mark the new version with Lerna:

lerna version 24.1.0-alpha0 --no-push --no-git-tag-version --force-publish --exact --yes

Commit all the changes:

git commit -a -m "chore: update main branch to Vaadin 24.1"

Create a PR to the main branch (example).

CI build updates

Add the new version branch to the CheckoutBranch parameter:

Miscellaneous

Generating icons

Re-generate SVG icon sets and icon fonts from individual SVG files for the packages that have them (e.g. vaadin-icons):

yarn icons

Using a local clone of the repo

When using a Vaadin app, you can modify the frontend build tool config to resolve the web components modules from your local clone, instead of the versions downloaded from npm registry.

Using webpack

Modify the webpack.config.js in the root folder as follows:

module.exports = merge(
  {
    resolve: {
      modules: ['/path/to/web-components/node_modules', 'node_modules'],
    },
  },
  flowDefaults,
);
Using Vite

Modify the vite.config.ts in the root folder as follows:

import path from 'path';
import { PluginOption, UserConfigFn } from 'vite';
import { overrideVaadinConfig } from './vite.generated';

function useLocalWebComponents(webComponentsNodeModulesPath: string): PluginOption {
  return {
    name: 'use-local-web-components',
    enforce: 'pre',
    config(config) {
      config.server = config.server ?? {};
      config.server.fs = config.server.fs ?? {};
      config.server.fs.allow = config.server.fs.allow ?? [];
      config.server.fs.allow.push(webComponentsNodeModulesPath);
      config.server.watch = config.server.watch ?? {};
      config.server.watch.ignored = [`!${webComponentsNodeModulesPath}/**`];
    },
    resolveId(id) {
      if (/^(@polymer|@vaadin)/.test(id)) {
        return this.resolve(path.join(webComponentsNodeModulesPath, id));
      }
    },
  };
}

const customConfig: UserConfigFn = (env) => ({
  // Disable the Vite dependencies pre-bundling
  optimizeDeps: {
    disabled: true,
  },
  plugins: [useLocalWebComponents('/path/to/web-components/node_modules')],
});

export default overrideVaadinConfig(customConfig);

Note Make sure that the path you provide is an absolute one and that it points to the node_modules directory in the web components monorepo.

Then run the following command in the web components monorepo:

yarn

This will symlink the individual component packages into the node_modules folder.

After that you can start / restart your application and it should use the source code from the monorepo.

Fixing npm dist-tag

When maintaining two stable majors (e.g. 22.0.x and 23.0.x), it is important to maintain latest npm tag. For example, we release 22.0.7 after 23.0.1 but we still want to keep latest pointing to 23.0.1.

Use the following script on main branch to run npm dist-tag for all packages:

./scripts/fixDistTag.sh