
Contributor's guide
===================

(For support, see [SUPPORT](./SUPPORT.md))

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

- Help someone at work or online fix their build problem.
- Answer/ask StackOverflow questions or on [Scala Discord][Discord].
- Create plugins that extend sbt's features.
- Migrate builds to sbt 2.x.
- Garden the issue tracker.
- Report issues.
- Patch the core (send pull requests to code).
- Review pull requests.
- Documentation fixes and contributions are as much welcome as to patching the core. Visit [sbt/website][documentation] to learn about how to contribute.

For the issue reporting guideslins, jump to [issues](#issues).

Ideas and proposals
-------------------

If you have an enhancement idea, or a general discussion, please follow the [sbt 2.0 RFC process](https://eed3si9n.com/sbt-2.0-rfc-process) or start a [Discussion][Discussions].

Patching the core (send pull requests)
--------------------------------------

This section describes how you can create Pull Requests (PRs) and describes coding standards we use when implementing them.

<a id="important"></a>
### **Important**:  ⚠️ Pull request must be tested with GitHub Actions or human-in-the-loop

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

- [ ] Before working on a pull request, please confirm with a Maintainer that a contribution is wanted for the issue.
- [ ] Before working on a pull request, please confirm that **you can reproduce the reported problem** using GitHub Actions or your computer.
- [ ] After making the code change, please confirm that **your change compiles, and has fixed the problem**.

Due to Gittensor bounties, sbt project is getting a high volume of pull request attempts, from
programmers with seemingly varying skill levels with regards to Scala or sbt.
In practice, this means that we do not have the bandwidth to play the QA role,
must minimize the review burden. Maintainers might close a PR if it fails to pass the CI in a few rounds.

If you can express the reproduction as a test that would be great, but often the problems require locally building sbt and running test builds yourself. For local testing, post screenshots or screencast to demonstrate that the fix works at least on your machine.

<a id="genai"></a>
### AI assisted contributions

Generally, it's fine to use AI tools to help you create Pull Requests for sbt as long as you adhere to the following guidelines:

- Pull requests created by AI must have been fully verified with **human-in-the-loop**. Actually run sbt to test your changes.
- **All AI usage in any form must be disclosed**. State in your PR description that you have used AI tools to assist in creating the PR.
- No third party materials are included in the output; or materials that are included in the output are in compliance with an open source license compatible with Apache License.
- Ensure that you review and understand all code generated by AI tools before including it in your PR - do not blindly trust the generated code. The final responsibility for the code in your PR lies with you.
- Blindly copy-pasting code from AI tools is detrimental as it might introduce security and stability risks to the project.

⚠️ Maintainers that spot untested, unexplainable, AI copy-pasted PRs will close the related PRs and block the user from making further contributions. ⚠️

In a perfect world, AI would produce high-quality, accurate work every time. But today, that reality depends on the driver of the AI. And today, most drivers of AI are just not good enough. So, until either the people get better, the AI gets better, or both, we have to have strict rules to protect Maintainers.

<a id="getting-started"></a>
### Getting started

1. Create a [fork](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of the repository.
2. Go to the Actions tab, and enable the workflows. **This will let you run the CI tests on your forked repository**.
3. [Clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) the forked repository to create a local copy.

### Branch to work against

sbt uses two branches for development:
Use the **default** branch set on GitHub for bug fixes. For backports, use the latest stable branch.

- Development branch: `develop`
- Stable branch: `1.$MINOR.x`, where `$MINOR` is current minor version (e.g. `1.12.x` during 1.12.x series)

The `develop` branch represents sbt 2.x, the next major sbt series.
The `stable` branch represents the current stable sbt 1.x release. Once sbt 2.x is released mostly bug fixes are back-ported to the stable branch.

### Pull Request guidelines

Before you submit a Pull Request (PR) from your forked repo, check that it meets these guidelines:

- Confirm that you can reproduce the problem prior to making the changes to the code.
- Include tests, either as scripted test or unit tests to your pull request, or screenshots from a manual test.
- Follow our project's [Commit message guideline](#commit).
- Follow our project's [Coding style and best practices][03].
- Sign the [Scala Contributor License Agreement](https://contribute.akka.io/contribute/cla/scala).
- Make sure your PR is small and focused on one change only - avoid adding unrelated changes, mixing adding features and refactoring. Keeping to that rule will make it easier to review your PR and will make it easier for core devs if they decide that your change should be cherry-picked to release it in a stable release of sbt.
- Maintainers will not merge a PR that regresses linting or does not pass CI tests (unless you have good justification that it a transient error or something that is being fixed in other PR).
- Maintainers will not merge a PR that breaks binary compatibility ("bincompat"). Run `mimaReportBinaryIssues` from the sbt shell.
- When merging PRs, Maintainer may use **Squash and Merge** which means then your PR will be merged as **one commit**, regardless of the number of commits in your PR. During the review cycle, you can keep a commit history for easier review.
- You can use any supported JDK version to run the tests, but the best is to check if it works for the oldest supported version (JDK 17 currently). In rare cases tests might fail with the oldest version when you use features that are available in newer JDK versions.
- Add an Apache header to all new files. Run `headerCreate` and sbt will put a copyright notice into it.

### Instruction to build just sbt

sbt has a number of sub-modules. If the change you are making is just contained in sbt/sbt (not one of the sub-modules),
you can use the `publishLocalBin` command to publish the sbt project to your local machine. This is helpful for testing your changes.

```bash
$ sbt
> publishLocalBin
```

See also [Development environment][02] and [Coding style and best practices][03].


### Testing

sbt features a testing infrastructure encompassing multiple testing methodologies designed to ensure reliability and functionality across different integrations. The testing framework includes:

- [Unit tests][04]
- [scripted tests][05]
- [Manual tests][06], using the locally baked sbt

### Tech stack

sbt code base uses a set of libraries and tooling, sometimes unique to sbt:

- [Tech stack][07]

<a id="commit"></a>
### Commit message guideline

Follow the following 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
```

1. (Optional) Subject should start with `[2.x]` for develop branch, and `[1.x]` for sbt 1.x
2. Subject should start with `fix` (bug fix), `feat` (new feature), `refactor`, `test`, `ci`, or `deps`
3. Subject should use imperative mood, for example Fix foo, Add bar.
4. Body should include Problem section, which summarizes the current understanding of the issue.
5. Body should include Solution section, which summarizes your approach to fixing the issue.
6. Do not at-mention people in the commit message.
7. Include "Generated-by" tag for Gen-AI tools.

### Instruction to build sbtn

```bash
$ sbt nativeImage
```

On macOS, the following can be used to target ARM64:

```bash
$ ARCHS=arm64 sbt nativeImage
```

<a id="issues"></a>
Reporting Issues
----------------

When you find a bug in sbt we want to hear about it. Your bug reports play an important part in making sbt more reliable and usable.

Effective bug reports are more likely to be fixed. These guidelines explain how to write such reports and pull requests.

Please open a GitHub issue when you are 90% sure it's an actual bug.

### Preliminaries

- Make sure your sbt version is up to date.
- Search [StackOverflow] and [Issues] to see whether your bug has already been reported.
- Open one case for each problem.
- Proceed to the next steps for details.

### What to report

The developers need three things from you: **steps**, **problems**, and **expectations**.

The most important thing to remember about bug reporting is to clearly distinguish facts and opinions.

#### Steps

What we need first is **the exact steps to reproduce your problems on our computers**. This is called *reproduction steps*, which is often shortened to "repro steps" or "steps." Describe your method of running sbt. Provide `build.sbt` that caused the problem and the version of sbt or Scala that was used. Provide sample Scala code if it's to do with incremental compilation. If possible, minimize the problem to reduce non-essential factors.

Repro steps are the most important part of a bug report. If we cannot reproduce the problem in one way or the other, the problem can't be fixed. Telling us the error messages is not enough.

#### Problems

Next, describe the problems, or what *you think* is the problem. It might be "obvious" to you that it's a problem, but it could actually be an intentional behavior for some backward compatibility etc. For compilation errors, include the stack trace. The more raw info the better.

#### Expectations

Same as the problems. Describe what *you think* should've happened.

#### Notes

Add any optional notes section to describe your analysis.

### Subject

The subject of the bug report doesn't matter. A more descriptive subject is certainly better, but a good subject really depends on the analysis of the problem, so don't worry too much about it. "StackOverflowError while name hashing is enabled" is good enough.

### Formatting

If possible, please format code or console outputs.

On GitHub it's:

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

On StackOverflow, it's:

```
<!-- language: lang-scala -->

    name := "foo"
```

Here's a simple sample case: [#327][327].
Finally, thank you for taking the time to report a problem.

Profiling sbt
-------------

See [PROFILING](./PROFILING.md)

  [StackOverflow]: https://stackoverflow.com/tags/sbt
  [Setup]: https://www.scala-sbt.org/release/docs/Getting-Started/Setup
  [Issues]: https://github.com/sbt/sbt/issues
  [Discussions]: https://github.com/sbt/sbt/discussions
  [327]: https://github.com/sbt/sbt/issues/327
  [documentation]: https://github.com/sbt/website
  [Discord]: https://discord.com/invite/scala
  [02]: contributing-docs/02_development_environment.md
  [03]: contributing-docs/03_coding_style.md
  [04]: contributing-docs/04_unit_tests.md
  [05]: contributing-docs/05_scripted_tests.md
  [06]: contributing-docs/06_manual_tests.md
  [07]: contributing-docs/07_tech_stack.md
