Skip to content

Latest commit

 

History

History
168 lines (104 loc) · 8.16 KB

CONTRIBUTING.md

File metadata and controls

168 lines (104 loc) · 8.16 KB
Raw

Contributing to Backpack Foundations

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:

Show/hide licence header 
Backpack - Skyscanner's Design System

Copyright 2016-<current year> Skyscanner Ltd

Licensed under the Apache License, Version 2.0 (the "License");
you may not use this file except in compliance with the License.
You may obtain a copy of the License at

  http://www.apache.org/licenses/LICENSE-2.0

Unless required by applicable law or agreed to in writing, software
distributed under the License is distributed on an "AS IS" BASIS,
WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
See the License for the specific language governing permissions and
limitations under the License.

Installing Node

Backpack is developed using Node. The required Node version is specified in .nvmrc.

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 to install the correct Node version.

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

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

Skyscanner employees only

Please ensure you have push rights to this repository, rather than forking the repository for contributions. Follow the "Engineering Contribution" guide in the Backpack space in Confluence to get access.

Install dependencies

Run npm install to install dependencies from npm.

A note on dependencies

Backpack Foundations 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 Foundations code depends on some things that must be built first.

Use npm run build to do this.

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 bpk-<android/ios/web/common> package.

Tokens are defined in the src/base directory. 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. If you need to add a new token and there is no 1:1 mapping from the existing aliases, add or multiply 2 aliases to achieve the desired value for your token.

After making changes to the base files (and updating imports when adding new files), run npm run build.

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

How to

Create a pull request to Backpack Foundations

For anything non-trivial, we strongly recommend speaking to somebody from Koala 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. If you are a Skyscanner employee, follow the "Engineering Contribution" guide in the Backpack space in Confluence to get push rights to this repository. Otherwise, you should 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 Koala 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.

Run the development environment

We use Storybook for our development environment. Run npm start to build foundations and start the Storybook server, then go to http://localhost:6006 in a web browser to view it. We use Storybook to visualise any changes to our web tokens storing foundational design values such as spacing, colours etc.

A story represents a category of tokens (and in the case of typography mixins) which store foundational design values such as spacing, colours etc. Any changes to an existing foundational token, or adding a new token to one of the existing categories will be automatically reflected in the story that corresponds to that category. Typography in Skyscanner is constructed in the form of Sass mixins. To add a new mixin you will have to manually add the name of the mixin in the list of existing styles which is stored in the typography stories folder.

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.
  • npm run lint:scss:fix to lint and try to automatically fix any SCSS errors.
Publish packages (Koala squad members only)
  • Update the unreleased changelog with every package that has changed, separating out BREAKING, 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 Koala 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.
  • Once the publish is done, move anything from UNRELEASED.md to CHANGELOG.md and push these changes directly to main.

Be aware that if bpk-foundations-common has changed, all packages in the repository will be updated as they all depend on bpk-foundations-common. Changing an existing token is almost always worth a "major" release, whereas adding a new token is usually a "minor" release.

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!