Generally, Finch follows a standard fork and pull model for contributions via GitHub pull requests. Thus, the contributing process looks as follows:

  1. Pick an issue
  2. Write code
  3. Write tests
  4. Write docs
  5. Submit a PR

Pick an issue

  • On Waffle, pick any issue from column “Ready”
  • On Github, leave a comment on the issue you picked to notify others that the issues is taken
  • On Gitter or Github, ask any question you may have while working on the issue

Write Code

Finch follows the Effective Scala code style guide. When in doubt, look around the codebase and see how it’s done elsewhere.

  • Code and comments should be formatted to a width no greater than 120 columns
  • Files should be exempt of trailing spaces
  • Each abstraction with corresponding implementations should live in its own Scala file, i.e Endpoint.scala
  • Each implicit conversion (if possible) should be defined in the corresponding companion object

That said, the Scala style checker sbt scalastyle should pass on the code.

Write Tests

Finch uses both ScalaTest and ScalaCheck with the following settings:

  • Every test should be a FlatSpec with Matchers and Checkers mixed in
  • An assertion in tests should be written with x shouldBe y
  • An assertion in properties (inside check) should be written with ===
  • Exceptions should be intercepted with an [Exception] shouldBe thrownBy(x)

Write Docs

Write clean and simple docs in the docs folder.

Submit a PR

  • PR should be submitted from a separate branch (use git checkout -b "fix-123")
  • PR should generally contain only one commit (use git commit --amend and git --force push or squash existing commits into one)
  • PR should not decrease the code coverage more than by 1%
  • PR’s commit message should use present tense and be capitalized properly (i.e., Fix #123: Add tests for Endpoint)