mirror of
https://github.com/HSLdevcom/digitransit-ui
synced 2025-07-06 18:00:35 +02:00
114 lines
4.4 KiB
Markdown
114 lines
4.4 KiB
Markdown
## 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](https://mochajs.org) and [chai](https://www.chaijs.com).
|
|
- 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](http://usejsdoc.org/) 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`](https://github.com/HSLdevcom/digitransit-component/blob/master/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
|
|
|
|
```sh
|
|
$ yarn run lint
|
|
```
|
|
|
|
* Follow the [AirBNB JavaScript code style](https://github.com/airbnb/javascript).
|
|
|
|
## 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](http://usejsdoc.org) documentation, and, finally, the
|
|
single exported class that the module provides.
|
|
* `test.js` - This file includes your [mocha](https://mochajs.org) and
|
|
[chai](https://www.chaijs.com) tests.
|
|
* `test.generated` - This file is generated from `test.js` using [Babel](babeljs.io).
|
|
* `package.json` - The [node](http://nodejs.org) 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](babeljs.io).
|
|
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:**:
|
|
|
|
```bash
|
|
$ 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`**
|
|
|
|
```bash
|
|
$ 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**
|
|
|
|
```bash
|
|
$ 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](https://yarnpkg.com) and [lerna](https://lernajs.io/) 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.
|