Thank you for deciding to contribute to Atomic Layout! This document will aim to make your contribution a smooth process, so please read it thoroughly. You're awesome.
$ git clone git@github.com:kettanaito/atomic-layout.gitAtomic Layout uses Yarn for package management. See the Yarn installation guidelines for instructions on how to install Yarn on your machine.
Verify that Yarn is installed by running:
$ yarn --version
1.19.0# Go to the library's directory
$ cd atomic-layout
# And install its dependencies
$ yarn install$ git checkout -b ISSUE_NUMBER-BRANCH_NAMEFor example:
git checkout -b 123-responsive-fix
Create, fix or experiment. Follow the Development guidelines for the development process overview.
$ git add path/to/changes.js
$ git commit -m 'Improves initial render'$ git push -u origin <BRANCH_NAME>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.
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!
When 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!
- TypeScript (JavaScript superset with strong types)
- Lerna (monorepo manager)
Atomic Layout is a mono-repository. This means that it contains multiple repositories listed in the packages/ directory. Examples of such repositories are:
packages/atomic-layout-corepackages/atomic-layout
When developing a feature or fixing an issue, navigate to the respective repository in the packages/ directory. For example, to fix an issue in atomic-layout library perform the following commands:
$ cd packages/atomic-layoutEach package has the set of similar commands for development and testing, but always check the list of commands in the respective package.json file. Instructions below will explain a general development workflow using packages/atomic-layout as an example.
To build the package in development mode run:
$ yarn start- Storybook (UI component explorer)
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 storybookTo 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 NewUseCaseReplace
NewUseCasewith 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.
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.
- Jest (JavaScript testing framework)
To run all unit tests of the library execute the following command:
$ yarn test:unitCreate 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
- Cypress (JavaScript end-to-end testing framework)
End-to-end tests are being run against a running Storybook instance. This means you should run Storybook first, before trying to run end-to-end tests.
To run E2E tests locally, perform:
$ yarn cypressThis launches a Cypress app with a list of test suites. Choose a specific test suite to run, or run all 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.
There is a shorthand command to verify your newly introduced changes on local:
$ yarn verifyThis is going to build and test all the packages. This command can also be run in a package's directory to verify that respective package.
In case of any questions please ping one of the library's maintainers on Discord. And don't worry, we are more than happy to assist you during the code review phase. Looking forward to your contributions!