Skip to content

Latest commit

 

History

History
75 lines (56 loc) · 2.89 KB

CONTRIBUTING.md

File metadata and controls

75 lines (56 loc) · 2.89 KB
Raw

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}"

This will add an entry in .plantir/revapi.yml to ignore future breaks of the same type.