Skip to content

Latest commit

 

History

History
242 lines (157 loc) · 10.7 KB

CONTRIBUTING.md

File metadata and controls

242 lines (157 loc) · 10.7 KB
Raw

Contributing to the Project

Hi 👋 Thanks for considering contributing! The aim of this doc is to guide you throughout the process of contributing to and help you better understand the Style Guide project.

Process

  1. Run this project locally (described below)
  2. Make your changes (including tests and documentation updates)
  3. Make sure all tests and linters are happy with your changes
  4. Open a PR
  5. Get your PR accepted by two of the maintainers

How to Run This Project Locally

Requirements

Step by Step Guide

  1. Clone this repository.
  2. Run yarn install.
  3. Run yarn build.
  4. Run yarn storybook.
  5. You should be able to access the docs in your browser by navigating to localhost:6006.

Docs

Remember that docs are an essential part of this project. Don't forget to update them whenever you change, add, or delete any components. Docs for each component are written in components/COMPONENT_NAME/*.stories.mdx|jsx files.

SCSS

We use the BEM naming convetion.

Modifier Dictionary

We have a standardized set of words you should use when adding modifiers to blocks.

  • If your component changes only in one dimension:

    • width: xnarrow narrow wide xwide full-width
    • height: xshort short tall xtall full-height

  • If it changes in both dimensions: xsmall small large xlarge

  • Behavior changes:

    • non-responsive
    • obscured vs standout
    • disabled
    • active vs inactive

  • Combinations of behaviors:

    • padding-wide
    • padding-tall
    • padding-large

All components are responsive by default, so there is no need for modifiers specific to responsiveness (exception: non-responsive).

React

Each component/container should have its own file. Components are dumb and should be written in pure function form. Each file should export the default module like so:

export default ComponentName;

File Location

Component and container files should be located next to .scss files in src/components directory. Documentation pages for components should be located in same directory with name {component-name}.stories.mdx.

Tests

Each component should be tested. We are using jest as a test runner/framework. Test files should be located next to component/container file with extension .spec.js

Storybook & Chromatic

There is also Chromatic visual regression tool which uses storybook stories to run tests. It is integrated with Github and being run on pull requests.

If you already have storybook stories, you can use them also for Chromatic. Run script:

$ node ./scripts/generate-chromatic-stories.js /path-to-your-storybook-file

It will generate script for Chromatic. That script just use existing component storybook stories, but you can modify it to omit or add some extra stories. Run storybook locally to check stories seen by Chromatic:

$ yarn storybook-chromatic

Then commit file and check Github PR to see Chromatic check status.

You can find more details how to work with Chromatic Confluence(INTERNAL)

Importing Dependencies

When importing dependencies, we are using global imports instead of relative ones.

Bad:

import Button, {variants as buttonVariants} from '../../buttons/Button';

Good:

import Button, {BUTTON_VARIANT} from 'components/buttons/Button';

or just:

import Button from 'components/buttons/Button';

<Button variant="solid">Button</Button>

Components options

Component options should be stored in a const object. Options should have singular form ("alignment" not "alignments") and capitalized names like:

const ALIGNMENT = {START: 'start', END: 'end'};

Each component should export its configuration options (if it have some).

export {DIRECTION, ALIGNMENT};

Layout and Helpers Documentation

Go to these links to find documentation about the Flexbox component and documentation regarding SASS mixins.

Adding icons process

  1. Your svg file has to be exported with a viewBox="0 0 512 512".
  2. Clean up the file: keep only xmlns and viewBox attributes on svg tag and remove the rest (eventually you can use data-fixedcolors attribute on svg icon which has to have fixed colors for some reason). There is no need to optimize a <path> since it will be optimized during build process with svgo.

Now, your file should look like:

  <svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512">
    <path ... />
  </svg>
  1. Add svg file to src/images/icons (in case of a basic icon), or relevant folder from src/images directory. Use snake_case as a naming convention.
  2. Define a new icon type in Icon.jsx. Add icon to a particular icon group in get-icon-group.js
  3. Run yarn build to re-generate icons.
  4. Run yarn storybook and go to icons section at http://localhost:6006/?path=/story/foundation-%E2%9C%A8-icons--page and find your newly added icon.
  5. Follow standard process of introducing changes to the style-guide.
  6. After releasing your changes, to use a new icon in your project you need to update the src of the icons in <script> you include on your page. This src is avaialble on the main page of docs (https://styleguide.brainly.com).

example:

<script src="https://styleguide.brainly.com/images/icons-0c5f18cafc.js"></script>

Adding logotypes

  1. Add new logo svg file to src/images/logos
  2. Update typings with new logo type using filename(without extension)
  3. Use new logo type as prop type in Logo component

Technical Discipline

Bumping the Release Version - this part is for maintainers

This project uses semver versioning. We follow SemVer:

  1. Bump first number - If your release breaks public API in any way - e.g. removed method, renamed class, different default parameters for method, new required parameters, removing components.
  2. Bump second number - If your release only extends public API and improves support, add new components, improves CSS.
  3. Bump the last number - Finally, if your release only fixes a bug w/o any API changes or introducing new features bump the last number.

To simplify version bumping you can use yarn version. It will patch package.json, create a corresponding commit, create a tag, and push those to git changes.

Preparing release

To bump the version correctly you should follow these steps:

  1. Merge approved, pending PR's into master.
  2. Create a branch with a bumped version according to the rules above, create tag and merge it (get approvals of course).
  3. Create proper, specific and detailed release note, with all the changes included in the release.
  4. Publish your newly prepared version of style-guide to NPM registry with npm publish command (do it from a fresh master branch containing commits with your changes and bumped version).
  5. Remember to let know contributors (before merge their PR, just mention in the comment that we are releasing a new version of the library) and Brainly engineers (slack channel would be a perfect place for that), that new version was released and it's ready to use.

Release Notes Template

Release notes title format contains tag and date: [TAG] (Date). For example v198.3.0 (4 Nov 2021)

Following headlines should be used in release notes:

  • Breaking Changes
  • Features
  • Bug Fixes
  • Maintenance
  • Dependency Updates
  • Documentation

Although we strictly adhere to Semver's rules, the style guide is built on many different levels, where certain changes may affect some parts of the consumer application. Please use the following labels to highlight these changes:

  • Change: Accessibility Marking release change containing accessibility related modification and improvements - these types of changes can affect the testing tools we use, such as react testing library. These tools often look at the accessibility tree, which changes are not covered by semantic versioning.

  • Change: Visual Marking release change containing visual changes e.g colors or size - means changing the color, size, positioning, etc. of a component. These changes are also not considered breaking changes, but they can affect the visual harmony of a design.

  • Change: Internal Layout Marking release change containing modifications inside internal layout or dom tree - this type of change is also not a breaking change in the sense of JS API, but CSS is often tricky and we should know when such modification occurred. For example, when we change the way things are displayed or restructure the internal component DOM tree.

Above tags should help testers and developers scan the release notes faster for possible regression points.

Preparing pre(alpha/beta) release

Style guide supports beta channel you can use to test your changes in prod like environment. To prepare pre release:

  • Push a git branch with your feature
  • Create a draft PR and label it with appropriate keyword (alpha/beta etc.)
  • Once you're ready to deploy beta release, bump version and create git tag:
    • run yarn version and type specific pre release version (follow the same principles as you would preparing standard release but put additional suffix to the version). e.g yarn version 220.6.0-beta.0. This command will bump your package version and create git tag. If you need another beta version in the same branch use subsequent integer -beta.1, beta.2 etc.
  • Push your changes (make sure you add --follow-tags option if not enabled globally)
  • Publish to npm with: npm publish --tag beta (or --tag alpha) command. Otherwise your release will be marked as latest
  • Deployed changes should be available in npm and on style guide dev cdn: https://styleguide-dev.brainly.com/X.X.X-beta.X/docs eg. https://styleguide-dev.brainly.com/220.3.0-beta.2/docs
  • After initial testing of alpha/beta, you can close your PR or conitnue working on it and merge to the master branch as an official feature

Troubleshooting

  • npm publish throws PUT https://registry.npmjs.org/brainly-style-guide - Not found - run npm login and try again

Code Style

All linter settings are based on our standarized frontend tools configs. To run the linters (and tests) you should use yarn test.