- 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).
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].
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.
- 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.
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 [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].
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]
<aid="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:
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.
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.
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.
