mirror of
https://github.com/HSLdevcom/digitransit-ui
synced 2025-06-15 20:30:41 +02:00
103 lines
3.7 KiB
Markdown
103 lines
3.7 KiB
Markdown
## 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](https://mochajs.org) and [chai](https://www.chaijs.com).
|
|
- 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](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-util/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-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](http://usejsdoc.org) documentation, and, finally, the
|
|
single exported function that the module provides.
|
|
* `test.js` - This file includes your [mocha](https://mochajs.org) and
|
|
[chai](https://www.chaijs.com) tests.
|
|
* `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.
|
|
|
|
## Publishing
|
|
|
|
Install lerna:
|
|
|
|
```bash
|
|
$ npm install -g lerna
|
|
```
|
|
|
|
Publish:
|
|
|
|
```bash
|
|
$ 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`**
|
|
|
|
```bash
|
|
$ 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**
|
|
|
|
```bash
|
|
$ 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](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.
|