Contributing to sbt

Guidelines, requirements, and best practices for contributing to sbt development

Contributions are welcome and greatly appreciated! There are many ways to contribute to the sbt ecosystem depending on your interests and skill level.

Ways to Contribute

Help Users

• Answer questions on Stack Overflow
• Help on Scala Discord
• Fix build problems at work or online

Documentation

• Fix documentation errors
• Add examples and clarifications
• Visit sbt/website

Code

• Patch the core
• Create plugins
• Review pull requests

Ecosystem

• Create plugins extending sbt
• Migrate builds to sbt 2.x
• Garden the issue tracker
• Report issues

Ideas and Proposals

For enhancement ideas or general discussions:

• Follow the sbt 2.0 RFC process
• Start a GitHub Discussion

Large changes should be discussed before implementation to ensure alignment with project goals and avoid wasted effort.

Pull Request Requirements

CRITICAL: Pull requests must be tested with GitHub Actions or human-in-the-loop validation before submission.

Before Working on a PR

1. Confirm the issue is valid

   Before working on a pull request, confirm with a Maintainer that a contribution is wanted for the issue.

2. Reproduce the problem

   Confirm that you can reproduce the reported problem using GitHub Actions or your computer.

   Given the wide user base and long history, not all reported issues are valid or relevant.

3. Verify your fix works

   After making code changes, confirm that your change compiles and has fixed the problem.

sbt receives a high volume of pull request attempts with varying quality. Maintainers may close PRs that fail CI in a few rounds due to limited bandwidth. We cannot play the QA role.

AI-Assisted Contributions

AI tools can help create pull requests, but strict rules apply:

Requirements

Human Verification (REQUIRED)

All AI-generated code must be fully verified with human-in-the-loop.

• Actually run sbt to test your changes
• Understand every line of generated code
• Do not blindly trust AI output
• Final responsibility lies with you

Disclosure (REQUIRED)

All AI usage in any form must be disclosed.

State in your PR description that you used AI tools. Include a “Generated-by” tag in your commit message:

Generated-by: Claude Sonnet 4.5

or

Generated-by: GitHub Copilot

License Compliance

• No third-party materials in output, OR
• Included materials comply with Apache License-compatible open source licenses

Code Understanding

Review and understand all AI-generated code before including it.

Blindly copy-pasting introduces security and stability risks.

Enforcement: Maintainers will close PRs and block users who submit untested, unexplainable, AI copy-pasted work.

Until people get better at using AI or AI gets better at producing reliable work, strict rules protect the project and maintainers.

Getting Started

1. Fork the repository

   Create a fork of the sbt repository.

2. Enable workflows

   Go to the Actions tab in your fork and enable workflows.

   This lets you run CI tests on your forked repository.

3. Clone your fork

   Clone the forked repository to create a local copy.

Branch to Work Against

sbt uses two branches for development:

Branch	Purpose
develop	Development branch for sbt 2.x (next major series)
1.x.x	Stable branch for current sbt 1.x releases (e.g., 1.12.x)

Use:

• develop for new features and bug fixes targeting sbt 2.x
• stable branch for backports to sbt 1.x

The default branch set on GitHub should be used for bug fixes. For backports, use the latest stable branch.

Pull Request Guidelines

Before submitting a PR, verify it meets these requirements:

Testing

Confirm problem reproduction

Reproduce the problem prior to making code changes.

Include tests

Add tests to your pull request:

• Scripted tests (for integration)
• Unit tests (for isolated logic)
• Screenshots from manual testing (if applicable)

See:

• Unit tests
• Scripted tests
• Manual tests

Code Quality

Follow commit message guidelines

See Commit Message Guideline below.

Follow coding style

Follow the project’s Coding style and best practices.

Run scalafmt:

sbt scalafmtAll

Sign the CLA

Sign the Scala Contributor License Agreement.

Apache header on new files

Add Apache headers to all new files:

sbt headerCreate

PR Scope

Keep PRs small and focused on one change only.

• Avoid unrelated changes
• Don’t mix features with refactoring
• Smaller PRs are easier to review and cherry-pick

CI and Compatibility

Pass all CI tests

Maintainers will not merge PRs that:

• Fail CI tests (without good justification)
• Regress linting

Ensure tests pass before requesting review.

Maintain binary compatibility

Maintainers will not merge PRs that break binary compatibility (“bincompat”).

Run from sbt shell:

mimaReportBinaryIssues

sbt MUST maintain backward binary compatibility across minor releases.

JDK version support

Test with the oldest supported JDK version (currently JDK 17).

You can use any supported JDK version to run tests, but verify compatibility with JDK 17.

Merging

Maintainers may use Squash and Merge, combining your PR into one commit regardless of commit count.

During review, you can keep a commit history for easier tracking.

Commit Message Guideline

Follow this template:

[2.x] fix: Fix consoleProject not starting

**Problem**
consoleProject doesn't work. REPL doesn't even start.

**Solution**
I made some progress into consoleProject.
At least Scala 3.7 REPL session will now start.

Generated-by: Claude Sonnet 4.5

Format Rules

1. (Optional) Subject should start with [2.x] for develop branch or [1.x] for sbt 1.x

2. Type prefix: Subject should start with:

   • fix - Bug fix
   • feat - New feature
   • refactor - Code refactoring
   • test - Test changes
   • ci - CI/CD changes
   • deps - Dependency updates

3. Imperative mood: Use “Fix foo”, “Add bar” (not “Fixed” or “Adds”)

4. Problem section: Summarize current understanding of the issue

5. Solution section: Summarize your approach to fixing it

6. No at-mentions: Do not at-mention people in commit messages

7. Generated-by tag: Include for Gen-AI tools

Building sbt Locally

Build just sbt

For changes contained only in sbt/sbt (not submodules):

sbt
> publishLocalBin

This publishes sbt to your local machine for testing.

See also:

• Development environment
• Coding style and best practices

Build sbtn (native client)

sbt nativeImage

On macOS for ARM64:

ARCHS=arm64 sbt nativeImage

Testing

sbt uses multiple testing methodologies:

Unit Tests

Test isolated functionality using Hedgehog or other test frameworks.

sbt test

See Unit tests documentation.

Scripted Tests

Integration tests for build scenarios.

sbt scripted

See Scripted tests documentation.

Manual Tests

Test using locally built sbt on real projects.

See Manual tests documentation.

Always add tests. For small-scope changes, prefer Hedgehog. For changes requiring file coordination and tasks, use scripted tests.

Tech Stack

sbt uses specialized libraries and tooling:

• Contraband - Type-safe data definitions
• Coursier - Dependency management (since sbt 1.3)
• sjson-new - JSON serialization
• Gigahorse - HTTP client
• Zinc - Incremental Scala compilation

See Tech stack documentation.

Reporting Issues

Open a GitHub issue when you’re 90% sure it’s an actual bug.

Preliminaries

1. Update sbt

   Make sure your sbt version is up to date.

2. Search existing issues

   Search Stack Overflow and GitHub Issues to see if your bug was already reported.

3. One issue per problem

   Open one case for each problem. Don’t combine multiple issues.

What to Report

Developers need three things: steps, problems, and expectations.

Steps (Most Important)

Exact steps to reproduce the problem on our computers.

Provide:

• Method of running sbt
• build.sbt that caused the problem
• sbt and Scala versions
• Sample Scala code (for incremental compilation issues)
• Minimized reproduction (reduce non-essential factors)

If we cannot reproduce the problem, it cannot be fixed. Error messages alone are insufficient.

Problems

Describe what you think is the problem.

• Include stack traces for compilation errors
• Provide raw information (more is better)
• What might be “obvious” to you may be intentional behavior

Expectations

Describe what you think should have happened.

Notes (Optional)

Add analysis, context, or additional observations.

Subject

A descriptive subject is better but don’t worry too much:

• Good: “StackOverflowError while name hashing is enabled”
• Acceptable: “sbt crashes”

Formatting

Format code and console outputs:

```scala
name := "foo"
```

See example issue #327.

Resources

Development Environment

Setup guide for sbt development

Coding Style

Style guide and best practices

Profiling

Performance profiling guide

Architecture

Understanding sbt’s architecture

Community

• Scala Discord - sbt channel
• Stack Overflow - Q&A
• GitHub Discussions - Ideas and proposals
• GitHub Issues - Bug reports

Thank you for taking the time to contribute to sbt!