Skip to content

Latest commit

 

History

History
117 lines (86 loc) · 6.38 KB

CONTRIBUTING.md

File metadata and controls

117 lines (86 loc) · 6.38 KB
Raw

Welcome!

Guardian for Apache Kafka follows the fork and pull development model. You can simply fork the repository, create and checkout a new branch and commit changes to that branch and then create a pull request once you are done.

Feel free to submit a PR earlier rather than later, this is recommended as it can spur discussion to see if you are on the right track. If you create a PR before its ready, we recommend using github's draft feature to clear indicate that a PR is still being worked on.

Setting up development environment

If you haven't already done so, before you get started you need to set up your machine for development. Guardian for Apache Kafka is written in Scala so a few steps are needed.

JDK

Guardian for Apache Kafka is developed on the latest stable branch of OpenJDK. For Windows and MacOS we recommend using AdoptOpenJDK to download the latest installer. For Linux its recommended installing OpenJDK through your distribution (but you can also use AdoptOpenJDK as a last resort)

Scala and sbt

Once you have installed JDK having Scala and sbt installed is recommended. Although some IDE's (such as Intellij) automatically handle Scala and sbt installation for you, it's still recommended having a standalone version so you can compile/test/run the project without an IDE/Editor. The Scala installation also comes with its own REPL which can aid in development.

We recommend following the official Scala2 documentation on how to install Scala

Editors/IDE's

The following editors are recommended for development with Scala. Although It's possible to use other environments since Scala is a strongly typed language using a well supported editor is beneficial.

Intellij IDEA

Intellij IDEA is one of the most used editors for Scala development. Upon installing of IDEA you need to install the scala plugin so it can recognize sbt projects. After installation of the plugin you can simply open the cloned guardian-for-apache-kafka and it should setup everything for you.

Metals

Metals is a Scala LSP implementation that supports various editors. The primary supported editor for Metals is Visual Studio Code along with relevant marketplace plugin.

Note that other editors can also be used with metals, documentation can be found here. Spacemacs an Emacs distribution also supports Metals via the Scala layer

Formatting

The codebase is formatted with scalafmt, as such the codebase needs to be formatted before submitting a PR.

Various runners for Scalafmt exist, such as

  • A sbt scalafmt plugin that lets you run scalafmt directly within sbt using
    • scalafmt to format base scala sources
    • test:scalafmt to format test scala sources
    • scalafmtSbt to format the build.sbt file
  • IntelliJ IDEA and VSCode will automatically detect projects with scalafmt and prompt you whether to use Scalafmt. See the scalafmt installation guide for more details
  • There are native builds of Scalafmt that let you run a scalafmt as a CLI tool, see the CLI section in scalafmt installation guide

Note that a github action exists which will check that your code is formatted whenever you create a PR. For more details read the documentation

sbt - Compiling, Building and Testing

We use sbt as the primary build tool for the project. When you run sbt by itself it will start a REPL session where you can type in commands, i.e.

  • compile will compile the entire project
  • test:compile will only compile the test sources
  • test will run the tests for the entire project
  • core/compile will only compile the core project. See build.sbt to get a reference for how the projects are named
  • publishLocal will publish the project into the local ~/.m2 repository
  • clean will clean all builds targets (including documentation) from the project. Note that sbt stores build in sub-directories named target
  • reload will reload sbt which is used when the sbt build definition is changed

Testing

As mentioned before testing is completely handled using sbt, there are no custom shell scripts that are required to set up environments unless otherwise noted in the testing docs (typically when tests run against actual services such as S3)

Docker

For integration tests Guardian for Apache Kafka uses docker to spin up services. For MacOS the best way to install docker is from the official website whereas if you are running Linux then consult your distribution/package manager/repository.

Since Guardian for Apache Kafka uses testcontainers you don't need to worry about starting/stopping the docker instances manually, this is automatically handled when you run the relevant test/s.

sbt - documentation

Documentation is also built within SBT, i.e.

  • docs/makeSite will compile documentation
  • docs/previewSite will compile documentation (if needed) and open the result in your system's default browser

For details about how the document generation works go here