Skip to content

Latest commit

 

History

History
79 lines (58 loc) · 4.67 KB

CONTRIBUTING.md

File metadata and controls

79 lines (58 loc) · 4.67 KB
Raw

Contributing to Cube.js

Thanks for taking the time for contribution to Cube.js! We're very welcoming community and while it's very much appreciated if you follow these guidelines it's not a requirement.

Code of Conduct

This project and everyone participating in it is governed by the Cube.js Code of Conduct. By participating, you are expected to uphold this code. Please report unacceptable behavior to [email protected].

Contributing Code Changes

Please review the preceding section before proposing a code change. This section documents how to do so.

When you contribute code, you affirm that the contribution is your original work and that you license the work to the project under the project’s open source license. Whether or not you state this explicitly, by submitting any copyrighted material via pull request, email, or other means you agree to license the material under the project’s open source license and warrant that you have the legal authority to do so.

Contribution Prerequisites

Cube.js works with Node.js 8+ and uses yarn as a package manager.

Development Workflow

Cube.js Client

  1. After cloning Cube.js repository run $ yarn in packages/cubejs-client-core and packages/cubejs-react to install dependencies.
  2. Use $ yarn link to add these packages to link registry.
  3. Perform required code changes.
  4. Use $ yarn build in the repository root to build CommonJS and UMD modules.
  5. Use $ yarn link @cubejs-client/core and/or $ yarn link @cubejs-client/react in your project to test changes applied.
  6. Use $ yarn test where available to test your changes.
  7. Ensure commit CommonJS and UMD modules as part of your commit.

Implementing Driver

  1. Copy existing driver package structure and name it in @cubejs-backend/<db-name>-driver format. @cubejs-backend/mysql-driver is very good candidate for copying this structure.
  2. Please do not copy CHANGELOG.md.
  3. Name driver class and adjust package.json, README.md accordingly.
  4. As a rule of thumb please use only Pure JS libraries as a dependencies where possible. It increases driver adoption rate a lot.
  5. Typically you need to implement only query() and testConnection() methods of driver. The rest will be done by BaseDriver class.
  6. If db requires connection pooling prefer use generic-pool implementation with settings similar to other db packages.
  7. Make sure your driver has release() method in case DB expects graceful shutdowns for connections.
  8. Please use yarn to add any dependencies and run $ yarn within the package before committing to ensure right yarn.lock is in place.
  9. Add this driver dependency to cubejs-server-core/core/index.js.

Implementing JDBC Driver

If there's existing JDBC Driver in place for Database of interest you can just create DbTypes configuration inside cubejs-jdbc-driver/driver/JDBCDriver.js. Most of times no additional adjustments required for base JDBCDriver implementation as JDBC is pretty standard. In case you need to tweak it a little bit please follow Implementing Driver steps but use JDBCDriver as your base driver class.

Implementing SQL Dialect

  1. Find most similar BaseQuery implementation in @cubejs-backend/schema-compiler/adapter.
  2. Copy it and adjust SQL generation accordingly.
  3. Add BaseQuery implementation to @cubejs-backend/schema-compiler/adapter/QueryBuilder.js with same name as driver.

Testing Schema Compiler

In order to run tests in cubejs-schema-compiler package you need to have running Docker on your machine. When it's up and running just use $ npm test in packages/cubejs-schema-compiler to execute tests.

Style guides

We're passionate about what code can do rather how it's formatted. But in order to make code and docs maintainable following style guides will be enforced. Following these guidelines is not a requirement but you can save some time for maintainers if you apply those to your contribution beforehand.

Code

  1. Run npm run lint in package before committing your changes. If package doesn't have lint script, please add it and run. There's one root .eslintrc.js file for all packages except client ones. Client packages has it's own .eslintrc.js files.
  2. Run npm test before committing if package has tests.
  3. Please use conventional commits name for your PR. It'll be used to build change logs. All PRs are merged using squash so only PR name matters.