Welcome to the contributing guide for Voca!
We love contributions from everyone. Thanks for your time and the will to improve Voca.
Please note we have a code of conduct, please follow it in all your interactions with the project.
Reporting an issue or suggest a feature
The GitHub issue tracker is the preferred channel for bug reports, change requests and submitting pull requests.
Before submitting one, make sure to search for existing issues. Please check to see if someone has already reported your problem or requested your idea.
The bug report must provide at least the following information:
- The expected behavior: how in your opinion the code should behave
- The actual behavior: how the code actually works
- Steps to reproduce: a step by step scenario how to reproduce the problem
- Technical details: useful info like browser type and version, Operating system, NodeJS version and other
Suggesting new features is welcomed
Creating pull requests
Pull requests are great
When contributing to this repository, please first discuss the change you wish to make via issue, email to firstname.lastname@example.org, or any other method with the owners of this repository before making a change.
When submitting the request please be sure:
- The pull request to pass the CI build
- The modification to be accompanied with unit tests
- The necessary updates to documentation are made
Voca codebase stands on the principles of modularity, small specialized functions and meaningful naming.
Testing is an inseparable part of the library, so every function must be tested in details and have almost 100% code coverage.
The library development environment requires Node version 4 and above.
nvm is a great tool to manage Node versions.
Configuring dev environment
Fork the repository, then clone it into your project directory.
Install the development dependencies within Voca source directory:
The most important development tools are:
- Babel to transform ES2015 code into ES5
- Rollup to bundle ES2015 modules into a single file
- Istanbul for code coverage report.
To build the bundles from the source code simply run:
npm run build
The command generates the following bundles:
dist/voca.jscompiled ES5 bundle, in UMD format compatible with CommonJS, RequireJS and Browser globals
dist/voca.min.jscompiled and minified ES5 bundle, also in UMD format.
dist/voca.min.js.mapcontains the source maps
dist_mod/index.jscompiled ES5 bundle in CommonJS format ready for NodeJS usage.
dist_mod/*.jscontains individual functions in CommonJS format.
Voca uses Mocha test framework.
The detailed testing is very important. Every function or part of the library must be tested with basic and advanced scenarios.
Tests must keep the same useful rules of modularity and clean code.
Run the library over the unit tests:
The library must be compatible with reasonable older browser. The CI build verifies using SauceLabs the compatibility with Chrome, Firefox, Edge 13+, IE 9+ and Safari 7+.
To verify the code coverage run the command:
npm run coverage
To maintain the coding style, the pre-commit hook automatically is linting the code.
You can find the linting rules in .eslintrc file.
To check the code using eslint tool run the command:
npm run eslint
The library uses JSDoc tool to automatically generate documentation from source code comments.
To generate the documentation, use the following command:
npm run jsdoc
Then open in browser the documentation html file