Contributing to Dinero.js
You want to contribute to Dinero.js and that's awesome
Before you dive in head first, there are a couple of guidelines to follow. Please make sure you read and understand them before you submit. Note that this isn't set in stone. Polite debate and suggestions are welcome, as long as it's done with the best interest of the library and the end users in mind.
❓ Should I contribute?
Pushing your first contribution can be intimidating. A great way to start is by fixing bugs: find an open and confirmed issue, and open a pull request that fixes it.
Dinero.js is a young project, so it doesn't have a well-defined scope yet. There are projects that widens what the library currently does, but unless explicitly specified you probably shouldn't develop new features. In doubt, ask first, this will ensure you don't do work for nothing.
- Fix bugs.
- Improve performance.
- Refactor with better design patterns.
- Improve build processes (speed, error handling, deprecations, etc.)
- Improve the docs (issues, typos, lack of clarity, etc.)
- Go against the library's philosophy (immutability, native internationalization, etc.)
- Make changes based on personal preferences rather than problem-solving.
- Develop features that aren't in the scope of the library (if not sure, ask before you code).
Yarn is the default package manager, which means
yarn.lock is the only versioned lock file. It's recommended you use Yarn, but most of the time you'll be fine with npm. If the install fails, or if you have to manipulate the dependencies, using Yarn will be mandatory.
To get started, clone the project and install the dependencies from your terminal:
$ git clone https://github.com/sarahdayan/dinero.js.git $ npm install # or yarn install, recommended
You can make sure your environment is able to test and build by running the following commands:
$ npm test # for unit tests $ npm build # to build dist files
If both commands succeed, you're good to go!
Dinero.js observes a few rules and conventions when it comes to code. Most of them are automated, but make sure you understand them before submitting changes.
Commitizen is used to standardize commit messages, generate the changelog and help semantic-release resolve the next version. Every commit must be done using cz-cli. Don't commit using
git commit or a GUI like SourceTree.
- Stage your changes
npm run cz
- Follow the terminal instructions
Prettier and ESLint will be run automatically before committing. If ESLint fails, the commit will not go through.
The library has a main file and services. Everything that's not directly related to the Dinero data structure should be abstracted into a service.
src/ ├── dinero.js └── services/ └── ...
Dinero.js is written using the ES6 notation. It uses ES modules, all new files must use this module system. Factory functions should be favored over ES6, and internal values should be encapsulated.
This is also an immutable library, and must remain this way.
The code should as much as possible follow the Clean Code concepts (unequivocal naming, SOLID principles, etc.)
The project uses Prettier for code formatting and ESLint for linting. Both will be run automatically when you commit, so you can go ahead and format as you like, it will be overridden anyway. Yet, contrary to Prettier, ESLint doesn't rewrite files. You need to fix linting issues yourself before you commit. To check for linting issues, run
npm run lint.
Dinero.js uses Jest for unit testing. Every public method should be unit tested.
Every spec file has its own spec file in the
test/unit/ directory. For example, all tests for
dinero.js are in
It's recommended you run tests before you commit, or at least before you open a pull request. Pull requests with failing tests won't be reviewed, so doing it beforehand will save you time.
$ npm test
Dinero.js uses the Intl API, which means you need Node with internationalization support enabled. The
full-icu option is recommended.
Dinero.js uses JSDoc to generate documentation. Every public method should be documented.
Every method should have a short description of:
- what it does,
- its parameters,
- the type of its return statement,
- if it throws and why,
Examples should be provided, and you should add an extra description if required to understand what the method does. This will be used in the generated documentation. Note that descriptions don't make up for poor naming or ambiguous methods. Only elaborate when necessary.
The documentation is hosted on GitHub Pages, which means generated pages are versioned. Yet, you shouldn't commit generated docs yourself: this will be done automatically during the CI workflow.
You can generate docs locally to make sure it displays properly, but don't commit the files.
$ npm run docs
Bug fixes must target
master, new features must target
develop. Thus, bug fixes are automatically deployed once merged. New merged features will remain on standby until
develop is manually merged into