Skip to content

contributing.adoc

Latest commit

 

History

History
193 lines (138 loc) · 6.17 KB

contributing.adoc

File metadata and controls

193 lines (138 loc) · 6.17 KB

Contributing

This document is for developers who wish to contribute to the interbit-ui-components package within the interbit repo. For general information on contributing to Interbit, see this Contribution Guide.

File structure

Path Description

src/assets/

Location for image assets.

src/components/

React components exported from this package.

src/components/BlockExplorer/

An interactive component that displays a chain’s state, its blocks, and actions dispatched.

src/components/Covenant/

A set of forms to dispatch chain actions. It is wrapped by LinkedCovenant and uses FormTable components.

src/components/Navigation/

A set of navigation components such as header, footer, and sidebar menus.

src/components/ReduxForm/

Helper functions for creating and validating Redux forms.

src/components/UIKit/

A set of simple UI components.

src/help/

Helper functionality for Redux forms, used with the EditableTable component. This directory is flagged for refactoring.

src/scss/bootstrap/

SCSS files from React Bootstrap. These files should not be edited.

src/scss/interbit/

SCSS files for Interbit styles. Each component has its own scss file which is imported in interbit.scss. Style overrides for React Bootstrap components are also located in this folder.

src/tests/exports.tests.js

A set of simple tests to check that exported components exist.

src/tests/uiKit.test.js

Rendering tests for UI Kit components.

src/styleguide/

Build files for React Styleguidist.

index.js

Export statements for components.

styleguide.config.js

Configuration file for React Styleguidist.

Creating components

Code structure

We are in the process of defining the code structure for Interbit UI components. At this time, we ask that contributing developers use the existing code as an example of how to structure your component’s code.

Simple, presentational components should go in the src/components/UIKit directory. More complex components should be in their own directory within src/components. Each component must be exported from src/index.js.

Presentational components should be dumb components. They:

  • receive data and callbacks as props exclusively.

  • don’t have their own state.

  • if components must have their own UI-related state (e.g. whether a modal is open), the state is managed by Redux. Do not use local component state management with this.setState().

SCSS

For each component:

  • The styles should be in their own file, say _my-component.scss, in the src/scss/interbit directory. This file should be imported in src/scss/interbit.scss.

  • The styles should be contained in a class named after the component and prefixed with ibweb-. For example, MyComponent should have a top-level class called ibweb-my-component. See src/scss/interbit/_footer.scss for how styles should be nested.

  • The CSS must be supported by the latest versions of Chrome, Firefox, Safari, and Edge. If in doubt, see caniuse.com.

Image assets

Image assets such as icons and illustrations should be placed in src/assets and should satisfy the following:

  • Icons files are placed in src/assets/icons.

  • Image asset files are in svg format wherever possible.

  • Files should not exceed 25 KB in size at this time.

Tests

Components must have an export test in src/tests/exports.test.js for each (sub)-component exported from src/index.js. This verifies that the component is in fact exported, and is usable externally.

UI Kit components must have, at the minimum, rendering tests in src/tests/uiKit.test.js. Interbit UI components uses Jest and Enzyme for testing and rendering components.

Documentation

Interbit’s documentation is generated by extracting JSDoc-style code comments and component example files from React components in a react-styleguidist-compatible way. Use the React Styleguidist Documenting guidelines for any new components you create. Specifically, for each component:

  • Give a brief description of the component before the class declaration.

  • Give a description of each prop that the component accepts

For example, the LinkBar component has the following code comments.

{% include "linkBar.js" %}

Each UI Kit component should be accompanied by an example file, MyComponent.md. React Styleguidist renders the components and JSDoc comments in a style guide. See React Styleguidist’s Documenting guidelines for details.

The example file should include:

  • An example of the rendered component.

  • An example of each variant of the component. For instance, we might apply className="blue" to a button component to render a blue button.

The following is LinkBar’s example `md file:

{% include "linkBar.markdown" %}

The style guide can be run locally from the interbit-ui-components directory by executing the following commands:

npm run styleguide:build
npm run styleguide

Modifying existing components

Tests

Run the test watcher from the interbit-ui-components directory with:

npm run test

Fix any tests that were broken after modifying the component, and add tests for any new behavior.

Documentation

Update the JSDoc code comments and the React Styleguidist examples to reflect the changes made to the component. Document any breaking changes.

Submitting your work

Create a fork of the Interbit repo and create a pull request from your fork to the Interbit repo. A member of the Interbit team will review your pull request, and once approved, will merge it into the master branch.