digitransit-ui/digitransit-component/CONTRIBUTING.md

How To Contribute

• Most work happens in sub modules. These are found in the packages directory prefixed with "digitransit-component-".
• If you would like to propose a new feature, open an issue.
• Always include tests. We use mocha and chai.
• digitransit-component modules are small, containing a single exported function.
• Avoid large dependencies at all costs.
• The README.md files in packages/digitransit-component-<module> are automatically generated from the JSDocs of the index.js. Please modify the JSDocs instead of modifying the README.md files directly. Then update/create the README.md executing ./scripts/generate-readmes or running yarn run docs from the root Dir directory.
• Finally run yarn run test from the project root folder to run all the tests required for deploying the project.

Code Style

To ensure code style, at the digitransit-ui root level run

$ yarn run lint

• Follow the AirBNB JavaScript code style.

Structure of a digitransit-component module

digitransit-component-<MODULE NAME>
│   index.generated
│   index.js
│   LICENSE-AGPL.txt
│   LICENSE-EUPL.txt
│   package.json
│   README.md
│   test.generated
│   test.js

To get started with a new module navigate to the root directory and run

$ yarn run digitransit-component-new-module <MODULE NAME>

it will create a new folder inside packages with a simple boilerplate for your module.

• index.js - This file contains, in order, the various modules you need to import, the JSDocs documentation, and, finally, the single exported class that the module provides.
• test.js - This file includes your mocha and chai tests.
• test.generated - This file is generated from test.js using Babel.
• package.json - The node metadata container file. Modules imported in index.js should be listed here under dependencies, and modules used in test.js should be listed under devDependencies. npm install looks to this file to install dependencies in ./node_modules.
• README.md - This README is generated automatically by running npm run docs from the project root level. DO NOT edit this file.
• LICENCE - Like the README, this file should not be edited.

Compiling with Babel

To get component working it must be compiled with Babel. Babel is a toolchain that is mainly used to convert ECMAScript 2015+ code into a backwards compatible version of JavaScript in current and older browsers or environments.

Navigate to the component's directory and run

$ yarn build:index && yarn build:test

it will create two files.

• index.generated - This file has been generated from index.js.
• test.generated - This file has been generated from test.js.

Publishing

Publish inside a module::

$ yarn publish

Documentation

To update digitransit-component's Documentation (README.md) use the following yarn run docs:

• inside a module: will only generate the docs of that module.
• main folder: will generate docs for all modules.

Documentation - Examples

Only builds docs for @digitransit-component/foo

$ cd ./digitransit-component/packages/digitransit-component-foo
$ yarn run digitransit-component-docs

> @digitransit-component/foo@1.0.0 docs /Users/foobar/projects/digitransit-ui/digitransit-component/packages/digitransit-component
> node ../../scripts/generate-readmes

Building Docs: @digitransit-component/foo

Builds docs for all modules

$ cd ./digitransit-ui
$ yarn run digitransit-component-docs
> @1.0.0 docs /Users/foobar/projects/digitransit-ui/digitransit-component
> node ./scripts/generate-readmes

Building Docs: @digitransit-component/foo
Building Docs: @digitransit-component/goo
Building Docs: @digitransit-component/hoo
....

Other Dependencies

• digitransit-component uses Yarn and lerna during the testing, packaging and publishing process.
  • Lerna will be automatically installed when you run yarn install in the root directory.
  • Yarn will need to be installed on your computer, installers are available via the yarn website.