Contributing to Scala's OSS Ecosystem

Contributing guide

Shortcut Description
Scala Contributors Get a peek into the inners of the Scala compiler.
Report an Issue File a bug report or a feature request.
Community Issues Get cracking on some easy to approach issues.
Scala 2 Hacker’s Guide Learn to write good code and improve your chances of contributing to the Scala galaxy.
Scala 3 Contributing Guide Walkthrough contributing to the Scala 3 compiler, along with a guide to compiler internals.

Why contribute a patch to Scala?

Just to name a few common reasons:

  • contributing a patch is the best way to make sure your desired changes will be available in the next Scala version
  • Scala is written in Scala, so going through the source code and patching it will improve your knowledge of Scala.
  • last but not least, it only takes a few accepted commits to make it into the Scala Contributor Hall of Fame.

The main Scala project consists of the standard Scala library, the Scala reflection and macros library, the Scala compiler and the Scaladoc tool. This means there’s plenty to choose from when deciding what to work on. Typically, the scaladoc tool provides a low entry point for new committers, so it is a good first step into contributing.

On the Scala bug tracker you will find the bugs that you could pick up. Once you decided on a ticket to look at, see the next step on how to proceed further.

If you are interested in contributing code, we ask you to sign the Scala Contributor License Agreement, which allows us to ensure that all code submitted to the project is unencumbered by copyrights or patents.

Bug-fix Check List

Originally these steps cover the Scala 2 compiler, but they also are relevant to the Scala 3 compiler.

This is the impatient developer’s checklist for the steps to submit a bug-fix pull request to the Scala project. For more information, description and justification for the steps, follow the links in that step. Further specific instructions for the release of Scala you are targeting can be found in the file for that GitHub branch

  1. Select a bug to fix from GitHub, or if you found the bug yourself and want to fix it, create a GitHub issue (but please make sure it’s not a duplicate).
  2. Optional (but recommended), announce your intention to work on the bug on Scala Contributors. After all, don’t you want to work on a team with these friendly people - it’s one of the perks of contributing.
  3. Fork the Scala repository and clone your fork (if you haven’t already).
  4. Create a feature branch to work on: use the branch name issue/NNNN where NNNN is the GitHub issue number.
  5. Fix the bug, or implement the new small feature, include new tests (yes, for bug fixes too).
  6. Test, rinse and test some more until all the tests pass.
  7. Commit your changes to your feature branch in your fork. Please choose your commit message based on the Git Hygiene section of the Scala project README.
  8. If necessary re-write git history so that commits are organized by major steps to the fix/feature. For bug fixes, a single commit is requested, for features several commits may be desirable (but each separate commit must compile and pass all tests)
  9. Submit a pull request.
  10. Work with a reviewer to get your pull request merged in.
  11. Celebrate!

Need more information or a little more hand-holding for the first one? We got you covered: take a read through the entire Hacker Guide (or the equivalent Scala 3 Contributing Guide) for an example of implementing a new feature (some steps can be skipped for bug fixes, this will be obvious from reading it, but many of the steps here will help with bug fixes too).

Larger Changes, New Features

For larger, more ambitious changes (e.g. new language features), the first step to making a change is to discuss it with the community at large, to make sure everyone agrees on the idea and on the implementation plan. Announce the change on the Scala Contributors mailing list and get developer feedback. For really complex changes, a Scala Improvement Process (SIP) document might be required, but the first step is always to discuss it on the mailing list and if a SIP is required, that will be discussed on the mailing list.

Contributions, big or small, simple or complex, controversial or undisputed, need to materialize as patches against the Scala project source tree. The hacker’s guides (Scala 2, or Scala 3) will explain how to materialize your idea into a full-fledged pull request against the Scala code base.

Contributors to this page: