Skip to content

Latest commit

 

History

History
160 lines (100 loc) · 6.53 KB

CONTRIBUTING.md

File metadata and controls

160 lines (100 loc) · 6.53 KB
Raw

Development

These instructions will get you a copy of the project up and running on your local machine for development and testing purposes.

Prerequisites

You need to install on your machine :

  • a recent version of Node.js
  • Git as version control system
  • Yarn as a dependency manager

Installing

In order to get your local development env running, you need to follow the steps below :

  1. Clone the project

    git clone ssh://git@stash.dashlane.com:7999/wp/dashlane-components.git

  2. Install dependencies

    yarn

  3. Build in watch mode

    yarn start

The last command will watch files located src and will recompile whenever they change. The resulted generated files will be located in build folder.

Developing

Once you have started the watched build on ui-component lib, you can start using this dev version in your project instead of the npm released version.

All you need to do is:

  1. Link the ui-component lib to register it as a link-able project in yarn

    yarn link

  2. Tell your project to use the local ui-component build

    yarn link @dashlane/ui-components

  3. You also need to link React version to your project's as it is a peer-dependency

       npm link PATH/TO/YOUR/PROJECT/node_modules/react

    (You will need to unlink React in order for tests to pass)

  1. Start devServer on your project

Developing on Docz

You may want to develop a new component while working on Docz to see your work without having to link it to a different project. To do so:

  1. Launch Docz in dev mode

    yarn docz:dev

  2. Launch typescript to type-check your work in a different terminal:

    yarn typing:watch

You will see the doc on http://localhost:3000

Contributing

Before contributing on this repo, please keep in mind that:

  • We aim to have dumb components in this lib : they are presentational components and they shouldn't do any data treatment or management.
  • We use styled-components for a better developers experience.
  • Every new component should be tested, if you are modifying an existing one you should update related tests.
  • Every new component should be documented, please follow the section below Documented components
  • Please follow the sample Button component as a reference/guide to create future ones.
  • Please follow the conventional commits guidelines for you commits messages Example of commit messages: docs: correct spelling of CHANGELOG& feat(navbar): add background color prop

Documented components

You can play/test existing components or your newly created one locally (without having to integrate it into another project) by using the fascinating tool called Docz.

All you need to do is :

  • Create a file called yourComponent.mdx
  • Import your component and start specifying its behaviour (its basic usage with defaults, specified props ...)
  • Add Docz <Playground> built-in component to enable live code testing on your component
  • Run yarn docz:dev in order to start a local server of our documented ui-components lib
  • Visualize your documentation: You can play/live test the components behaviour by clicking on <> button

Code linting and formatting

We use prettier to format and eslint with typescript settings to lint our code.

Good to know :

  • It's convenient to configure your ide in order automatically format your files. Please follow this Editor Integration documentation.

  • Otherwise, we have a yarn task that formats your git staged files for you. You can simply run yarn pretty-quick

  • We also have an automatic task that runs a prettier and eslint check on git staged files everytime you attempt to create a new commit in order to be sure that things are OK

  • A check on the message format is executed as well on commit-msg hook using commitlint tool

  • we also execute the task yarn exec-docz-update on post-commit that will check if we have added or updated any Docz documentation (by modifying or adding any .mdx file), regenerate new built documentation and add push it through a new dedicated commit : in this way, we assure that https://dashlane.github.io/ui-components is always up to date.

  • Jest tests are run everytime you attempt to push new code on remote

  • Theses checks/rules are quite strict but very beneficial: they protect us from having 💩 slip into our code base

  • In order to avoid repetitive/manual work to create svg icons components (since they are all similar only the content of the svg changes [see src/atoms/icons folder]), we choose to generate them. All you need to do is to update/add content in src/design-tokens/icons-defs.json and run the task yarn generate-icon-components. This commandline runs a script located in config/generator/generateIcons.js that generates all specified icons in the json mentioned earlier following the config/generator/IconComponentTemplate.tsx.hbs template. It also updates the src/atoms/svg/index.ts to export the generated components. Note: this process is safe: no duplicated components/exports will be generated (if files already exist they will be overridden)

Running tests

We use Jest as testing framework and assertion library. We use Enzyme as a testing utility for react components and snapshot tests to make sure that our UI does not change unexpectedly.

  • To run tests, please execute

    yarn test

  • To run tests in watch mode, please execute

    yarn test:watch

Build

In order to build this library you can simply run

yarn build

which will generate in the folder build a transpiled and minified components as ES6 modules (to allow tree-shaking) with the associated typing.

Release

In order to relase and publish the library, run

yarn release

This will build your project, automaticaly assign a new version to the package and publish it.