Skip to content

Latest commit

 

History

History
125 lines (90 loc) · 6 KB

CONTRIBUTING.md

File metadata and controls

125 lines (90 loc) · 6 KB

Contributing

We'd love for you to contribute to our source code and to make Collab UI React even better than it is today! Below are the guidelines to follow.

Table of Contents

Running the project locally

  • Run the start script which will build and watch the library, then serve it at localhost:4400
    • yarn start:react from the root (collab-ui) directory
    • yarn start from the react (collab-ui/react) directory
  • You can access the playground localhost:4400/playground

Adding a new component

  1. cd into the react directory: cd react/
  2. For a new component, create a directory in the "src/lib/" directory: src/lib/<ComponentName>/
  3. Add a component file for your component: <ComponentName>/index.js
  4. Add a "tests" directory and file for the snapshot tests: /tests/index.spec.js
  5. Add an "examples" directory and file for the documentation: /examples/<componentName>-default.html

Your components directory should look like this:

└── src
    └── lib
        └── <Component>                     # component directory
            ├── index.js                    # component file
            ├── examples                    # examples directory
            |   └── <Component>Default.js   # default example component
            └── tests                       # tests directory
                ├── index.spec.js           # component unit test
                └── __snapshots__           # snapshots directory (will be generated Jest)
                    └── index.spec.js.snap  # snapshots file (will be generated by Jest)

Testing

All UI components of collab-ui-react are unit-tested using two approaches:

  1. Jest (Typically for snapshot testing)
    • Jest is a JavaScript test runner maintained and recommended by Facebook. Jest is a batteries included unit testing framework and few of its benefits includes being fast, feature rich, and integrates perfectly with Babel. Jest provide Painless JavaScript Testing.
    • Snapshot tests are a very useful tool whenever you want to make sure your UI does not change unexpectedly.
    • A typical snapshot test case for a web app renders a UI component, takes a screenshot, then compares it to a reference image stored alongside the test. The test will fail if the two images do not match: either the change is unexpected, or the screenshot needs to be updated to the new version of the UI component.
    • Snapshot testing covers most cases of Unit testing.
  2. Enzyme (Typically for Functional/DOM testing)
    • Enzyme's API is meant to be intuitive and flexible by mimicking jQuery's API for DOM manipulation and traversal.
    • Enzyme works well for functionality testing with shallow rendering of components.
    • It features jQuery like API for quick DOM traversal.
    • Use it when a runtime feature is to be tested that cannot be covered using snapshot testing, for example: Click behavior on a component.
    • All properties used in components are invariably tested using inbuilt React PropTypes.

Documentation

  • The document site related to component usage/example is documented using components within the examples directory in each component directory.

  • Any change/creation of additional components should include modified example file.

Design Principles

Components

  • Collab UI React follows components and their compositions based architecture with focus on simplicity, flexibility and performance.

  • Only statefull components are implemented as subclass of React.Component. Others are simple stateless functions or PureComponents.

  • Source is written is ES6 and processed through babel to generate minified ES6 modules (ready to import).

Coding Guidelines

  • Prefer ES6 classes over prototypes.
class Abc {
  publicmethod() {}
  render() {}
}
  • Prefer arrow functions =>, over the function keyword except when defining classes or methods.
  • Use PascalCase for classes and components, lowerCamelCase for variables and functions, SCREAMING_SNAKE_CASE for constants, _singleLeadingUnderscore for private variables and functions.
  • Prefer template strings over string concatenation.
let name = 'World!';
let concatenatedvalue_correct = \`Hello ${name} everyone!\`; // ✔
let concatenatedvalue_wrong = 'Hello ' + name + ' everyone'; // ✕
  • Prefer promises over callbacks.
  • Prefer array functions like map and forEach over for loops.
  • Use const for declaring variables that will never be re-assigned, and let otherwise.
  • Avoid var to declare variables.
  • Use lowercase names for folder names and PascalCase for component folder names.

Please follow the coding style of the current code base. Collab UI React uses eslint for ES6/JS and stylelint for scss/css, so if possible, enable linting in your editor to get realtime feedback. The linting rules can be run manually as below

npm run lint

Tasks

All tasks are made available as npm or yarn scripts without any bloat that comes with usual task runners (like grunt, gulp, etc).

Utils

  • There are few shared utility that are kept aside as helpers under 'src' but outside components folder.

License

By contributing your code to the @collab-ui/react GitHub repository, you agree to license your contribution under the MIT license.