Skip to content

Latest commit

 

History

History
247 lines (156 loc) · 7.22 KB

CONTRIBUTING.md

File metadata and controls

247 lines (156 loc) · 7.22 KB

Contributing guidelines

Thank you for deciding to contribute to Atomic Layout! We've put up a few useful instructions on how to get started and get going with your contributions. Please take some time to read through them.

Preparations

1. Fork the repository

$ git clone [email protected]:kettanaito/atomic-layout.git

2. Install Yarn

We are using Yarn for package management. Please refer to the Yarn installation for instructions on how to install Yarn on your machine.

3. Install dependencies

$ cd atomic-layout
$ yarn install

Git workflow

1. Create a feature branch

$ git checkout -b ISSUE_NUMBER-BRANCH_NAME

For example: git checkout -b 123-responsive-fix

2. Develop

Create, fix and experiment. Follow the Development guidelines for the development process overview.

3. Commit your changes

$ git add path/to/changes.js
$ git commit -m 'Improves initial render'

4. Push to the remote

$ git push -u origin <BRANCH_NAME>

5. Open a pull request

Click on the link below to create a new Pull request. Please choose base: master on the left and compare: <YOUR_BRANCH_NAME> on the right. Click on "Create pull request" button to confirm.

Once created, fill in the Pull request template with the requested information.

6. Undergo a code review

Once your pull request is opened one of the core contributors of the library will give you a code review. Please be patient and polite, we're on the same side here!

7. Welcome to contributors!

Once approved, your changes will be merged into master by one of the library's core maintainers. With your avatar proudly shining in the Contributors list, welcome to the contributors!

Development

  • TypeScript (JavaScript superset with strong types)

Running the build

$ yarn start

Running Storybook

Atomic Layout development is done in Storybook. Each story is a usage scenario and end-to-end test suite at the same time. Please check the existing stories before creating a new one, there is a high change such usage scenario already exists.

$ yarn storybook

Creating a story

To create a new story choose a proper folder in the examples/ directory and create a new MyNewStory.jsx file. Please refer to the existing stories for reference and inspiration.

Here's an example of how a new story may look like:

// examples/components/Composition/NewUseCase.jsx
import React from 'react'
import { Composition } from 'atomic-layout'

const NewUseCase = () => (
  <Composition templateCols="250px 1fr">
    <span id="first">First</span>
    <span id="second">Second</span>
  </Composition>
)

export default NewUseCase

Replace NewUseCase with the cammelCase title of the use case you are describing.

After the story is created add it to the list of all stories in examples/index.js:

// examples/index.js
const NewUseCase = require('./components/Composition/NewUseCase')

storiesOf('Components|Composition', module).add('New use case', NewUseCase)

If you are adding a new story you must also add a new E2E test that tests that story. A story without a corresponding E2E test is considered unnecessary.

Verify your story by Running Storybook and finding your new story in the respective section in Storybook.

New Storybook story verification

Testing

There are two kinds of tests in Atomic Layout: unit and end-to-end (E2E) tests. Depending on the type of your changes you would need to run one or both test types to verify your changes.

Unit tests

Running unit tests

  • Jest (JavaScript testing framework)

To run all unit tests of the library execute the following command:

$ yarn test:unit

Writing unit tests

Create a [filename].spec.ts file alongside the module you would like to test. Refer to the existing test suites (*.spec.ts) for and inspiration.

Here's an example of a small unit test:

import myNewModule from './my-new-module'

describe('My New Module', () => {
  describe('given a number', () => {
    it('should multiply by 2', () => {
      expect(myNewModule(5)).toEqual(10)
    })
  })
})

Verify your newly added unit test by running:

$ yarn jest path/to/my-new-module.spec.ts

Unit test verification

Useful unit testing materials:

E2E tests

  • Cypress (JavaScript end-to-end testing framework)

End-to-end tests run against a running Storybook instance. This means you should run Storybook first, before trying to run end-to-end tests.

Running E2E tests

To run E2E tests locally, perform:

$ yarn cypress

This launches a Cypress app with a list of test suites. Choose a specific test suite to run, or run all tests.

Writing E2E tests

E2E tests assert certain usage scenarios. First, add a usage scenario by Creating a new story in Storybook.

Once you've created the usage scenario, add a new [scenario].test.js module next to your newly created scenario. This will be your end-to-end test suite.

Here's an example of what an E2E test suite may look like:

describe('New usage scenario', () => {
  before(() => {
    cy.loadStory(['components', 'composition'], ['new-use-case'])
  })

  it('should render two columns', () => {
    cy.get('#first').should('be.visible')
    cy.get('#second').should('be.visible')
  })
})

Please refer to the existing end-to-end tests for inspiration.

Verify your newly created E2E test by Running E2E tests and choosing your E2E test suite in the list of available tests.

Unit test verification

Useful E2E testing materials:

Verifying changes

There is a shorthand command to verify your introduced changes:

$ yarn ci

This is going to build the library, Storybook, and run unit and E2E tests. It's recommended you perform this command before creating a Pull request.

Afterword

Use these guidelines as a runbook for your contributions. Be productive, and see you soon in Pull requests!