First off, thanks for considering making a contribution to Liquid Oxygen! 👍
The following is a set of guidelines for contributing to Liquid Oxygen. These are not rules. So use your best judgment, and feel free to propose changes to this document in a pull request.
This project and everyone who participates in it is governed by our Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to email@example.com.
This section guides you through submitting a bug report for Liquid. Following these guidelines helps maintainers and the community understand your report ✏️, reproduce the behavior 💻💻, and find related reports 🔎.
Before creating bug reports, please check this list as you might find out that you do not need to create one. Fill out our bug report template and include as many details as possible. The more information we have, the more likely we will be able to resolve the issue in a short time.
Bugs are tracked as GitHub issues. Create an issue and provide the following information by filling in the template.
Explain the problem and include additional details to help maintainers reproduce the problem:
Provide more context by answering these questions:
Include details about your configuration and environment:
npm list @emdgroup-liquid/liquidinside the working directory of your project.
This section guides you through submitting a feature request for Liquid, including completely new components, new features to existing components and minor improvements to existing functionality. Following these guidelines helps maintainers and the community understand your request ✏️ and find related requests 🔎.
You can upvote a feature request, if it has the
needed: votes label, with a 👍 reaction on the top comment of the issue. The more votes, the higher we prioritize the request.
Feature requests are tracked as GitHub issues. Use our feature request template to create a feature request and include as many details as possible:
npm list @emdgroup-liquid/liquidinside the working directory of your project.
Unsure where to begin contributing to Liquid Oxygen? You can start by looking through
help wanted issues:
Both issue lists are sorted by total number of comments. While not perfect, the number of comments is a reasonable indicator for the impact your contribution can have.
Before you can contribute any code, you will most likely want to setup a local development environment. Follow these steps to get started:
Install Git, Node.js and pnpm.
Clone the project (or your fork of it):
git clone firstname.lastname@example.org:emdgroup-liquid/liquid.git
corepack enable && pnpm i
src/liquidfolder by running the project build task (this step is only required before starting the local dev server for the first time):
pnpm run build
pnpm run start
This project consists of different parts and pieces, each with its own purpose. Familiarize yourself with these parts and pieces, so that you find your way quicker to the relevant spot where you would like to contribute.
├── README.md ├── CODE_OF_CONDUCT.md ├── CONTRIBUTING.md ├── SECURITY.md ├── LICENSE.md ├── package.json # Please have a look at the scripts section inside the │ # package.json file. │ # You can also run `npm run` to get a list of all │ # available commands. ├── .devcontainer │ └── devcontainer.json # GitHub codespaces dev container configuration. ├── .github │ └── workflows/ci-cd.yml # CI/CD pipeline config file. ├── .vscode │ └── task.json # Task configurations for Visual Studio Code. ├── .env # The .env file is not under version control. │ # It contains sensitive data, such as credentials │ # used to authenticate oneself against │ # an API. We currenly do this for fetching design │ # tokens from Figma. ├── bin # Contains scripts to be included in the bundle │ # for execution with npx. ├── config # Folder containing all sorts of configuration files. │ ├── .eleventy.cjs # The Liquid Oxygen docs site is powered by 11ty. │ │ # See https://www.11ty.dev/ │ ├── .eslintrc.cjs # eslint is used for linting ts and tsx files. │ │ # Please make sure to enable eslint in your code editor. │ ├── .prettierrc.json # prettier ensures a consistent code style. Please make │ │ # sure to enable prettier in your code editor of choice. │ ├── .releaserc.cjs # Config file for semantic-release. See │ │ # https://semantic-release.gitbook.io/semantic-release/ │ ├── commitlint.config.cjs # We use conventional commits and semantic release. │ ├── postcss.config.docs.cjs # PostCSS config file for the docs site CSS processing. │ ├── postcss.config.cjs # PostCSS config file for Liquid CSS processing. │ ├── stencil.config.docs.ts # Stencil config file for the docs site. │ ├── stylelint.config.cjs # Stylelint config file. See section about linting │ │ # further below. │ ├── tsconfig.docs.json # Typescript config file for components used for the │ │ # docs site. │ ├── tsconfig.react.json # Typescript config file for react component bindings. │ └── tsconfig.vue.json # Typescript config file for vue component bindings. ├── .npmignore # The .npmignore file is used to keep the package size │ # to a minimum. │ # More about this below. ├── dist # Here is the main juice which gets published to npm. ├── dist_docs # This folder is served during development. It contains │ # the docs site as well as the necessary liquid files. ├── screenshot # This directory contains files related to visual │ # regression testing with Stencil. See │ # https://stenciljs.com/docs/screenshot-visual-diff ├── scripts # Contains bash or node script files executed via │ # npm script commands. ├── src # The source folder. │ ├── _data # This folder contains data files. │ │ │ # See https://www.11ty.dev/docs/data-global/ │ │ └── env.cjs # Environment variables injected during generation of │ │ # the docs site. │ ├── docs # Everything inside this folder is for developing the │ │ │ # docs site. │ │ ├── assets # Static assets for the docs page reside here. │ │ ├── components # Docs components live here. │ │ ├── global # Docs global styles live here. │ │ ├── includes │ │ │ ├── layout.njk # The docs site is powered by 11ty. This is the default │ │ │ │ # 11ty layout file for the docs site. │ │ │ │ # See https://www.11ty.dev/docs/layouts/ │ │ │ └── redirect.njk # This layout file handles redirects on pages behind │ │ │ │ # authentication. │ │ ├── layouts # There is one layout component which lives inside this │ │ │ # folder. │ │ ├── pages # This folder contains markdown files for general │ │ │ # documentation pages, legal stuff and the 404 page. │ │ └── utils # Contains docs utililty files. │ └── liquid # Liquid Oxygen source code lives here. │ ├── components # This folder contains all Liquid components including │ │ # tests and docs. │ ├── global # Here we have global styles. Mainly CSS custom │ │ # properties, such as variables for colors, theming, │ │ # typography, spacings, shadows etc. │ │ # Note that most of these files are auto-generated │ │ # using design tokens. │ └── utils # Contains utilities shared between components. ├── stencil.config.ts # Stencil config file for Liquid components. ├── tsconfig.json # Typescript config file for Liquid components. └── pnpm-lock.yaml # We use pnpm and this is the respective lock file.
As you can see, Liquid Oxygen currenly has a straight forward project structure:
One repo, one package.json, no workspaces, just two main directories inside the
src/docs/ for the docs site and
src/liquid/ for the component library.
You probably noticed by now that we use eslint, prettier and stylelint in this project to enforce some code style conventions. Please make sure to enable these tools in your code editor of choice.
Some things are not linted but are still important:
ld-and docs components with
rem; absolute length units should be avoided (borders and outlines may count as an exception to the rule).
ld-and use BEM.
.shadowsuffix in the file name (for instance
ld-sidenav.shadow.css). This will ensure the CSS does not end up in the CSS components bundle.
:wheretrick to reduce CSS speceficity to zero, make sure the properties affected are not potential candidates for reset and normalize styles.
We also use husky for running Git hooks which in turn run lint tasks before you commit or push something. Which brings us to the next point...
Commit messages are linted with commitlint and should adhere to the Conventional Commits specification. This ensures that semantic release, which we use for automated release management, works as it is supposed to. Please squash commits which together solve a specific task before submitting a pull request. This not only ensures a clean Git history, but also a clean changelog which is generated by semantic release automatically upon release.
Branch names are linted using the following regular expression before push:
There are multiple commands available as npm scripts for running different kinds of tests: Unit tests, functional (e2e) tests as well as visual regression tests (using screenshots) are handled by Stencil. We also run accessibility tests within the functional test suits using axe-core.
You execute tests either by running one of the npm scripts which start with
test (see package.json) or by executing the respective test commands directly with the options needed. Please refer to the docs of each test runner in question for available options.
The following examples should help you start testing quickly and efficiently.
pnpm run test:unit
pnpm run test:watch
ld-tabscomponent in watch mode with coverage: #
stencil test --spec --coverage --no-cache --watch=all -- ld-tabs ld-tablist
pnpm run test:e2e
stencil test --screenshot --e2e -- src/liquid/components/ld-sidenav/test/ld-sidenav.e2e.ts && pnpm run test:e2e:cleanup
pnpm run test:compare_screenshots
ts-node scripts/screenshots.ts rm -c ld-sidenav
When you have implemented changes in your local clone or fork of our Liquid Oxygen repository, it is time to create a pull request in order to integrate these changes. But before you do that, please follow these steps to make sure your contribution gets considered by the Liquid Oxygen maintainers:
While the prerequisites above must be satisfied prior to having your pull request reviewed, the reviewer(s) may ask you to complete additional design work, tests, or other changes before your pull request can be ultimately accepted.
If you want to dive deeper into the technology stack used in the Liquid Oxygen project, check out the below list of selected documentation sites and articles we found valuable:
Let us know if we should add something! 🤓