Skip to content

Latest commit

 

History

History
206 lines (120 loc) · 9.68 KB

CONTRIBUTING.md

File metadata and controls

206 lines (120 loc) · 9.68 KB

Contributing to Backpack

You want to help us enable Skyscanner to create beautiful, coherent products at scale? That's awesome! ❤️

Table of contents

Prerequisites

Licence

By contributing your code, you agree to license your contribution under the terms of the APLv2.

All files are released with the Apache 2.0 licence.

If you are adding a new file it should have a header comment containing licence information from the following file: license.

Decisions

Conventions and squad decisions are kept in the decisions folder. We recommend familiarising yourself with these.

Installing Node

Backpack is developed using Node, using the following versions:

  • LTS/Erbium (Node ^12.13.0)
  • ^6.12.0 (npm)

This is enforced using a pre-install hook that calls out to ensure-node-env.

If you use nvm or nave to manage your Node environment, Backpack has built-in support for these. Just run nvm use or nave auto to install the correct Node version.

To install npm, use npm install --global npm@^6.12.0.

Android, iOS and React Native

Backpack also supports React Native, plus native Android and iOS.

They can be found at backpack-android and backpack-ios and backpack-react-native

Code style

Backpack uses a combination of ESLint and Prettier to enforce coding styles. ESLint runs as a pre-commit hook, so it isn't possible to commit code that causes ESLint to fail.

We recommend that you install a plugin to your editor to run ESLint automatically, which will then show you any errors inline. You can even enable an option to fix ESLint errors automatically upon saving.

Getting started

Getting the code

You should pull code down using the following command

git clone https://github.com/YOUR_USERNAME/Backpack.git

Install dependencies

Run npm install to install dependencies from npm.

A note on dependencies

Backpack is a multi-package repository, also known as a monorepo. This means that instead of having one code repository for each npm package, we manage them all inside this single repository.

We use Lerna to achieve this. Lerna links packages together inside this repo by 'bootstrapping'.

When you run npm install, Lerna is bootstrapped automatically as a post-install hook. However, if you change dependencies within a package, you will need to run Lerna manually with npm run bootstrap.

Build the code

Backpack's code depends on some things that must be built first, such as icon fonts, SVGs and tokens.

Use npm run build to do this.

Run the development environment

We use Storybook for our development environment. Run npm start to start the Storybook server, then go to http://localhost:9001 in a web browser to view it.

Adding icons

If you want to add icons, please discuss them with us first.

Once they're signed off, you can raise a request and attach the SVG files. If you're feeling heroic and want to make the PR yourself, just copy the correctly named SVG files to the lg and sm directories in @skyscanner/bpk-svgs/src/icons/ and then run npm run build.

Adding a new component

If you want to add a new component, we will need the following:

  • Design (Figma file)
  • Associated tokens
  • Sass mixin(s)
  • React component
  • Stories
  • Tests
  • Documentation (Including main README.md)

Design

Figma is the preferred format for non-technical folks. We’d appreciate if you could provide an exact match of your component in Figma format together with folders for each state e.g. disabled, expanded etc.

Tokens

Any visual CSS parameters of the component, such as color, margins, paddings etc. should not live as magic numbers in the component code, but as tokens in the @skyscanner/bpk-foundations-web package.

Tokens are defined in the src/base directory (with the exception of product-specific tokens, which are in other subdirectories). Tokens come in two layers: In aliases.json, all base tokens are defined with concrete values, such as colours, numbers and sizes. The other files then map those aliases to tokens for specific elements.

You should probably not touch aliases.json, as our colour palette or grid rarely changes.

Sass mixins

All Sass mixins are defined in the bpk-mixins package. The package also exposes the Sass variables from the @skyscanner/bpk-foundations-web package.

If you add a new file of mixins, for example for a new atom, make sure you add the file to the imports in _index.scss.

React component

Use npm run create-component to create a new skeleton React component. Once this is created, use existing components for code style inspiration.

We use CSS Modules along with BEM to prevent collisions and accidental overwrites in CSS.

To maintain React 16.4 compatibility, please do not use newer features of React such as Hooks.

When creating (S)CSS files, follow the CSS Module naming convention by using the .module.(s)css extension.

Documentation

Our documentation consists of two parts: Sassdoc, which is automatically generated from the bpk-mixin sources, and the main documentation.

Sassdoc

As mentioned, the Sassdoc are automatically generated from source and comments. If you want to double check, you can generate them using npm run sassdoc and start a static server to browse the docs, but usually this is not necessary.

Take a look at some of the mixin source files to see how to annotate your Sass to generate proper Sassdoc.

Backpack documentation

For documentation changes, please see our Backpack docs repo.

How to

Create a pull request to Backpack

For anything non-trivial, we strongly recommend speaking to somebody from Backpack squad before starting work on a PR. This lets us pass on any advice or knowledge we already have about the work you're proposing. It might even be something we're already working on. After this, follow the steps below.

  1. Fork the repository.
  2. Create a new branch.
  3. Make your changes.
  4. Commit and push your new branch.
  5. Submit a pull request.
  6. Notify someone in Backpack squad or drop a note in #backpack.

Don't forget to update UNRELEASED.md for any user-facing changes.

Bear in mind that small, incremental pull requests are likely to be reviewed faster.

Run tests

npm test will pick up any files that end in -test.js, so you don't need to do anything to make Jest pick them up.

You can also run the tests in 'watch mode', which means the process will continually run and run tests every time files change. Use npm run jest:watch to do this.

There are also visual regression tests, powered by Storyshots and jest-image-snapshot. Use npm run jest:visual to run these. They rely on the dist-storybook folder being populated with a pre-built Storybook first, which can be generated with npm run storybook:dist.

Visual regression tests run on all Storybook stories titled 'Visual test'.

Run linters manually
  • npm run lint to lint both JS and SCSS.
  • npm run lint:js to lint JS.
  • npm run lint:js:fix to lint and try to automatically fix any errors.
  • npm run lint:scss to lint SCSS.
Publish packages (Backpack squad members only)
  • Update the unreleased changelog with every package that has changed, separating out BRAKING, ADDED and FIXED changes. See CHANGELOG_FORMAT.md for tips.
    • Some useful commands for determining "what's changed?":
      • npm run lerna updated
      • npm run lerna diff <package-name>
  • Make sure you are an owner of the npm packages (speak to a member of the Backpack squad).
  • Run npm run release (this will run several checks and then lerna publish). Do not run npm publish.
  • You’ll be asked to confirm the new versions and descriptions for every package that has changed.
  • If you need to make changes you can exit without confirming and no changes will be made.

When a component is released for the first time on npm, remember to add the component to the Skyscanner organisation through the npm UI.

And finally..

If you have any questions at all, don't hesitate to get in touch. We love to talk all things Backpack and we look forward to seeing your contribution!