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.
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 conduct@cube.dev.
Please review the following sections before proposing code changes.
- Cube.js Client is MIT licensed.
- Cube.js Backend is Apache 2.0 licensed.
By contributing to Cube Dev, Inc., You accept and agree to the terms and conditions in the Developer Certificate of Origin for Your present and future Contributions submitted to Cube Dev, Inc. Your contribution includes any submissions to the Cube.js repository when you click on such buttons as Propose changes
or Create pull request
. Except for the licenses granted herein, You reserve all right, title, and interest in and to Your Contributions.
We publish our open source roadmap every quarter and discuss them during our monthly community calls. You can find our roadmap under projects in our Cube.js repository.
- Find issues where we need help. Search for issues with either
good first issue
and/orhelp wanted
labels. - Follow the directions in the Getting Started guide to get Cube.js up and running (incl. the Developer Playground).
- Clone the Cube.js repo.
- Submit your Pull Request.
- Testing: Please include test(s) for your code contribution. See some of the test examples for drivers and backend.
- Documentation: When new features are added or there are changes to existing features that require updates to documentation, we encourage you to add/update any missing documentation in the
/docs
folder. To update an existing documentation page, you can simply click on theEdit this page
button on the top right corner of the documentation page. - Relevant team(s) will be pinged automatically for a review based on information in the
CODEOWNERS
file.
Cube.js works with Node.js 10+ and uses Yarn as a package manager.
Cube.js offers two different types of Docker image:
- Stable (building from published release on npm)
- Dev (building from source files, needed to test unpublished changes)
For more information, take a look at Docker Development Guide.
- After cloning Cube.js repository run
yarn install
inpackages/cubejs-docker
to install dependencies. - Use
docker build -t cubejs/cube:latest -f latest.Dockerfile
inpackages/cubejs-docker
to build stable docker image.
- After cloning Cube.js repository run
yarn install
to install dependencies. - Use
docker build -t cubejs/cube:dev -f dev.Dockerfile ../../
to build stable development image.
- After cloning Cube.js repository run
yarn install
in root directory. - Use
yarn link
to add these packages to link registry. - Perform required code changes.
- Use
yarn build
in the repository root to build CommonJS and UMD modules. - Use
yarn link @cubejs-client/core
and/oryarn link @cubejs-client/react
in your project to test changes applied. - Use
yarn test
where available to test your changes. - Ensure that any CommonJS and UMD modules are included as part of your commit.
To get set up quickly, you can perform 1) and 2) with one line from the cube.js
clone root folder:
$ cd packages/cubejs-client-core && yarn && yarn link && cd ../.. && cd packages/cubejs-client-react && yarn && yarn link && cd ../..
If you are going to develop a JDBC driver, you need to install Java with JDK.
Cube.js is written in a mixture of plain JavaScript and TypeScript. TypeScript is preferred for new code.
Attention: Cube.js uses TypeScript configured in incremental mode, which uses cache to speed up compilation,
but in some cases, you can run into a problem with a not recompiled file. To fix it, we recommend running$ yarn clean
and$ yarn tsc
.
- Clone the Cube.js repository,
git clone https://github.com/cube-js/cube.js
. - Run
yarn install
in the root directory. - Run
yarn build
in the root directory to build the frontend dependent packages. - Run
yarn build
inpackages/cubejs-playground
to build the frontend. - Run
yarn tsc:watch
to start the TypeScript compiler in watch mode. - Run
yarn link
inpackages/cubejs-<pkg>
for the drivers and dependent packages you intend to modify. - Run
yarn install
inpackages/cubejs-<pkg>
to install dependencies for drivers and dependent packages. - Run
yarn link @cubejs-backend/<pkg>
inpackages/cubejs-server-core
to link drivers and dependent packages. - Run
yarn link
inpackages/cubejs-server-core
. - Create or choose an existing project for testing.
- Run
yarn link @cubejs-backend/server-core
in your project directory. - Run
yarn dev
to start your testing project and verify changes.
- Follow all the steps from the previous section. Make sure that the
yarn tsc:watch
daemon is running in the background. - Open the cube.js project in WebStorm.
- Create a new configuration, using
./node_modules/.bin/cubejs-server
for Node Parameters and the directory of your test project for Working directory. - Run/Debug dev cube.js servers using the new configuration.
- Copy existing driver package structure and name it in
@cubejs-backend/<db-name>-driver
format.@cubejs-backend/mysql-driver
is a very good candidate for copying this structure. - Please do not copy CHANGELOG.md.
- Name driver class and adjust package.json, README.md accordingly.
- As a rule of thumb please use only Pure JS libraries as a dependencies where possible. It increases driver adoption rate a lot.
- Typically, you need to implement only
query()
andtestConnection()
methods of driver. The rest will be done byBaseDriver
class. - If db requires connection pooling prefer use
generic-pool
implementation with settings similar to other db packages. - Make sure your driver has
release()
method in case DB expects graceful shutdowns for connections. - Please use yarn to add any dependencies and run
$ yarn
within the package before committing to ensure rightyarn.lock
is in place. - Add this driver dependency to cubejs-server-core/core/DriverDependencies.js.
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 the time no additional adjustments required for base JDBCDriver
implementation as JDBC is pretty standard.
In case you need to tweak it a little please follow Implementing Driver steps but use JDBCDriver
as your base driver class.
- Find the most similar
BaseQuery
implementation in@cubejs-backend/schema-compiler/adapter
. - Copy it, adjust SQL generation accordingly and put it in driver package. Driver package will obtain
@cubejs-backend/schema-compiler
dependency from that point. - Add
static dialectClass()
method to your driver class which returnsBaseQuery
implementation for the database. For example:
const { BaseDriver } = require('@cubejs-backend/query-orchestrator');
const FooQuery = require('./FooQuery');
class FooDriver extends BaseDriver {
// ...
static dialectClass() {
return FooQuery;
}
}
If driver class contains static dialectClass()
method it'll be used to lookup corresponding SQL dialect. Otherwise, it will use the default dialect for the database type.
Cube.js looks up cubejs-{dbType}-driver
package among installed modules to fullfil driver dependency if there's no corresponding default driver for the specified database type.
For example one can publish cubejs-foo-driver
npm package to fullfil driver dependency for the foo
database type.
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 yarn test
in packages/cubejs-schema-compiler
to execute tests.
If you want to make changes to the Cube.js client packages and test them locally in your project you can do it the following way:
- Make the desired changes and run
yarn build
in the root directory (you can also useyarn watch
) - Go to the
~/some-path/cube.js/packages/cubejs-client-core
directory and runyarn link
. (You'll see the messages Registered "@cubejs-client/core") - Now you can link it in your project (e.g. /my-project/dashboard-app). You can do so running
yarn link "@cubejs-client/core"
If you want to make changes to the @cubejs-client/react
package you'll need a few extra steps
- Go to your project's node_modules directory and find the react package (e.g. /my-project/dashboard-app/node_modules/react and run
yarn link
- Go to the
~/some-path/cube.js/packages/cubejs-client-react
directory and runyarn link react
Now your project will be using the local packages.
NOTE: You might need to restart your project after linking the packages.
Please use cargo test
to test packages and cargo fmt
to format code before commit.
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.
- Run
yarn 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. - Run
yarn test
before committing if package has tests. - 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.
- For the scope part of commit name please use package name if it's within one package or don't use it if change spans multiple packages. For example
feat(@cubejs-backend/server-core):
orfix(cubestore):
. - Do not reformat code you aren't really changing unless it's absolutely necessary (e.g. fixing linter). Such changes make it really hard to use git blame feature when we need to find a commit where line change of interest was introduced.