Contributing¶
If you would like to contribute code to this project you can do so through GitHub by forking the repository and sending a pull request.
When submitting code, please make every effort to follow existing conventions and style in order to keep the code as readable as possible.
Before your code can be accepted into the project you must also sign the Individual Contributor License Agreement (CLA).
Building Misk locally¶
Install and activate hermit: https://cashapp.github.io/hermit/
Use gradle to run all Kotlin tests locally:
gradle build
misk-hibernate tests expect a mysql server running on localhost:3306 with no password set on
the root user. You might stand up a server with a docker image, e.g.
docker run -d --rm --name "mysql-57" -p 3306:3306 -e MYSQL_ALLOW_EMPTY_PASSWORD=true -e MYSQL_LOG_CONSOLE=true mysql:5.7 --sql-mode=""
Misk may download these Docker images as part of its tests. Because tests can time out, pre-downloading these can help resolve timeouts.
alpine:latest
amazon/dynamodb-local:latest
cockroachdb/cockroach
gcr.io/cloud-spanner-emulator/emulator
pingcap/tidb
postgres
redis:6.2-alpine
softwaremill/elasticmq
vitess/base
Breaking changes¶
We integrate both Kotlin Binary Compatibility Validator and Revapi into our build pipeline to automatically detect breaking changes that could affect existing clients.
Kotlin Binary Compatibility Validator¶
This tool checks for changes to the public binary API. The plugin generates a dump of the current API and compares it to the previous version. If a binary incompatibility is detected, the build will fail.
If the change is intentional, you can run the :apiDump task and commit the resulting changes
to the .api files. .api files should not have removals and additions in the same change so
that downstream apps do not immediately run into backwards-compatibility issues.
This runs as part of gradle check task, or you can call directly with gradle apiCheck.
Revapi¶
Similarly, revapi detects binary compatibility changes by analyzing API differences. Unlike the
binary-compatibility-validator, this does not complain when adding new methods or when
introducing new arguments with default values that is accompanied by @JvmOverloads.
To accept a break identified by revapi, run the command suggested by the plugin:
gradle revapiAcceptBreak --justification "{why this is ok}" \
--code "{revapi check code}" \
--old "{optional revapi description of old element}" \
--new "{optional revapi description of new element}"