132 lines (94 sloc) 3.87 KB

How to Contribute

Instructions on how to contribute to Quill project.

Building the project using Docker

The only dependency you need to build Quill locally is Docker. Instructions on how to install Docker can be found here.

If you are running Linux, you should also install Docker Compose separately, as described here.

After installing Docker and Docker Compose you have to setup databases:

docker-compose run --rm setup

After that you are ready to build and test the project. The following setp describes how to test the project with sbt built within docker image. If you would like to use your local sbt, please visit Building locally.

To build and test the project:

docker-compose run --rm sbt sbt test

Building Scala.js targets

The Scala.js targets are disabled by default, use sbt "project quill-with-js" to enable them. The CI build also sets this project quill-with-js to force the Scala.js compilation.

Changing database schema

If any file that creates a database schema was changed then you have to setup the databases again:

docker-compose down && docker-compose run --rm setup

Changing docker configuration

If build/Dockerfile-sbt, build/Dockerfile-setup, docker-compose.yml or any file used by them was changed then you have to rebuild docker images and to setup the databases again:

docker-compose down && docker-compose build && docker-compose run --rm setup


Running tests

Run all tests:

docker-compose run --rm sbt sbt test

Run specific test:

docker-compose run --rm sbt sbt "test-only io.getquill.context.sql.SqlQuerySpec"

Run all tests in specific sub-project:

docker-compose run --rm sbt sbt "project quill-async" test

Run specific test in specific sub-project:

docker-compose run --rm sbt sbt "project quill-sqlJVM" "test-only io.getquill.context.sql.SqlQuerySpec"

Debugging tests

  1. Run sbt in interactive mode with docker container ports mapped to the host:
docker-compose run --service-ports --rm sbt
  1. Attach debugger to port 15005 of your docker host. In IntelliJ IDEA you should create Remote Run/Debug Configuration, change it port to 15005.
  2. In sbt command line run tests with test or test specific spec by passing full name to test-only:
> test-only io.getquill.context.sql.SqlQuerySpec

Pull Request

In order to contribute to the project, just do as follows:

  1. Fork the project
  2. Build it locally
  3. Code
  4. Compile (file will be formatted)
  5. Run the tests through docker-compose run sbt sbt test
  6. If you made changes in *.md files, run docker-compose run sbt sbt tut to validate them
  7. If everything is ok, commit and push to your fork
  8. Create a Pull Request, we'll be glad to review it

File Formatting

Scalariform is used as file formatting tool in this project. Every time you compile the project in sbt, file formatting will be triggered.

Building locally using Docker only for databases

To restart your database service with database ports exposed to your host machine run:

docker-compose down && docker-compose run --rm --service-ports setup

After that we need to set some environment variables in order to run sbt locally.

export CASSANDRA_PORT=19042
export MYSQL_HOST=
export MYSQL_PORT=13306
export POSTGRES_PORT=15432
export SQL_SERVER_PORT=11433
export ORIENTDB_PORT=12424

Where is address of local docker. If you have non-local docker change it depending on your settings.

Finally, you can use sbt locally.