digitransit-ui/digitransit-search-util/CONTRIBUTING.md

How To Contribute

• Most work happens in sub modules. These are found in the packages directory prefixed with "digitransit-util-".
• If you would like to propose a new feature, open an issue.
• Always include tests. We use mocha and chai.
• Digitransit-util modules are small, containing a single exported function.
• Avoid large dependencies at all costs.
• The README.md files in packages/digitransit-util-<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-util module

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

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

$ yarn run digitransit-ui-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 function that the module provides.
• test.js - This file includes your mocha and chai tests.
• 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.

Publishing

Install lerna:

$ npm install -g lerna

Publish:

$ lerna publish

Documentation

To update Digitransit-util'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-util/foo

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

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

Building Docs: @digitransit-util/foo

Builds docs for all modules

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

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

Other Dependencies

• Digitransit-util 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.