7.2 KiB

Raw Permalink Blame History

Sending pull request

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

Getting started

Create a fork of the repository and clone it to create a local copy.

Protect your identity

Once a PR is merged, the commit author's (and any co-author's) name and email address become permanently public as part of the commit history and cannot be changed or removed afterward.

You can verify your current configuration by running the following commands in your terminal within your local sbt repository:

git config --get user.name
git config --get user.email

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:

Include tests, either as scripted test, unit tests, or both, to your pull request.
Follow our project's Commit message guideline.
Follow our project's Coding style and best practices.
Sign the Scala Contributor License Agreement.
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 8 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.

Gen-AI assisted contributions

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

State in your PR description that you have used Gen-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 Gen-AI tools before including it in your PR - do not blindly trust the generated code.
State in your PR description that you have used Gen-AI tools to assist in creating the PR.
Remember that the final responsibility for the code in your PR lies with you, regardless of whether it was generated by a tool or written by you.
Blindly copy-pasting code from Gen-AI tools is detrimental as it might introduce security and stability risks to the project. Maintainers that spot such behaviours MAY close the related PRs and/or block the user from making further contributions.

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

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

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
scripted tests
Manual tests, using the locally baked sbt

Tech stack

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

Tech stack

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.

$ sbt
> publishLocalBin

Instruction to build sbtn

$ sbt nativeImage

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

$ ARCHS=arm64 sbt nativeImage

Instruction to build all modules from source

When working on a change that requires changing one or more sub modules, the source code for these modules can be pulled in by running the following script (instead of building them from Maven for example and not being able to change the source code for these sub-modules).

Install the current stable binary release of sbt (see [Setup]), which will be used to build sbt from source.

Get the source code.

$ mkdir sbt-modules
$ cd sbt-modules
$ for i in sbt io zinc; do \
  git clone https://github.com/sbt/$i.git && (cd $i; git checkout -b develop origin/develop)
done
$ cd sbt
$ ./sbt-allsources.sh

To build and publish all components locally,

$ ./sbt-allsources.sh
sbt:sbtRoot> publishLocalAllModule

Updating Scala version

See https://github.com/sbt/sbt/pull/6522 for the list of files to change for Scala version upgrade.

Diagnosing build failures

Globally included plugins can interfere building sbt; if you are getting errors building sbt, try disabling all globally included plugins and try again.

Random tidbits

Import statements

You'd need alternative DSL import since you can't rely on sbt package object.

// for slash syntax
import sbt.SlashSyntax0.given

// for IO
import sbt.io.syntax.*

7.2 KiB Raw Permalink Blame History