diff --git a/AGENTS.md b/AGENTS.md index 6bbcdc62f..950f7cca0 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -15,8 +15,10 @@ sbt compile Pull reuqest guideline ---------------------- -- Follow the PR guidance in [contributing-docs/01_pull_request.md](contributing-docs/01_pull_request.md). -- In the commit message, include "Generated-by" tag for Gen-AI tools. +- Follow the PR guidance in [CONTRIBUTING.md](./CONTRIBUTING.md). +- [ ] 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**. +- [ ] In the commit message, include "Generated-by" tag for Gen-AI tools. Coding style ------------ diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 03e3e3c28..cfaf8cf84 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,27 +1,23 @@ - [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 -Contributing -============ +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. -- Maintain and update [documentation]. - 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 ------------------- @@ -31,8 +27,137 @@ If you have an enhancement idea, or a general discussion, please follow the [sbt Patching the core (send pull requests) -------------------------------------- -See a more detailed documentation [Sending pull request](contributing-docs/01_pull_request.md). +This section describes how you can create Pull Requests (PRs) and describes coding standards we use when implementing them. + +### **Important**: ⚠️ Please test before sending a PR + +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. + + +### 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. +- 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 untested, unexplainable, Gen-AI copy-pasted PRs will close the related PRs and block the user from making further contributions. ⚠️ + + +### 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] + + +### 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 +``` + + Reporting Issues ---------------- @@ -42,10 +167,6 @@ Effective bug reports are more likely to be fixed. These guidelines explain how Please open a GitHub issue when you are 90% sure it's an actual bug. -### Notes about Documentation - -Documentation fixes and contributions are as much welcome as to patching the core. Visit [sbt/website][documentation] to learn about how to contribute. - ### Preliminaries - Make sure your sbt version is up to date. @@ -106,3 +227,17 @@ 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 diff --git a/README.md b/README.md index de7c3d568..872cad434 100644 --- a/README.md +++ b/README.md @@ -41,7 +41,7 @@ several GitHub repositories, including this one. Issues and Pull Requests ------------------------ -Please read [CONTRIBUTING] carefully before opening a GitHub Issue, and [Contributor's guide][contributing-docs] before opening a pull request. +Please read [CONTRIBUTING] carefully before opening a GitHub Issue or a pull request. If you're looking for an idea for a contribution, issues labeled with [good first issue](https://github.com/sbt/sbt/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22) or diff --git a/contributing-docs/01_pull_request.md b/contributing-docs/01_pull_request.md deleted file mode 100644 index 6ce11a232..000000000 --- a/contributing-docs/01_pull_request.md +++ /dev/null @@ -1,166 +0,0 @@ -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](https://docs.github.com/en/github/getting-started-with-github/fork-a-repo) of the repository and [clone](https://docs.github.com/en/github/creating-cloning-and-archiving-repositories/cloning-a-repository) 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: - -```bash -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](#commit). -- Follow our project's [Coding style and best practices](03_coding_style.md). -- 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 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 -``` - -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. - -### 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_unit_tests.md) -- [scripted tests](05_scripted_tests.md) -- [Manual tests](06_manual_tests.md), using the locally baked sbt - -### Tech stack - -sbt code base uses a set of libraries and tooling, sometimes unique to sbt: - -- [Tech stack](07_tech_stack.md) - -### 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 -``` - -### Instruction to build sbtn - -```bash -$ sbt nativeImage -``` - -On macOS, the following can be used to target ARM64: - -```bash -$ 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). - -1. Install the current stable binary release of sbt (see [Setup]), which will be used to build sbt from source. -2. Get the source code. - - ```bash - $ 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 - ``` - -3. To build and publish all components locally, - - ```bash - $ ./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. - -```scala -// for slash syntax -import sbt.SlashSyntax0.given - -// for IO -import sbt.io.syntax.* -``` diff --git a/contributing-docs/02_development_environment.md b/contributing-docs/02_development_environment.md index 898ee870c..0ace6b0e4 100644 --- a/contributing-docs/02_development_environment.md +++ b/contributing-docs/02_development_environment.md @@ -4,7 +4,7 @@ Development environment Generally sbt can be developed on any environment that supports JDK and sbt. This includes macOS, Linux, and modern Windows. -1. Install JDK (We recommend Azul Zulu JDK 8, 11, or 17 on macOS, and Temurin elsewhere). +1. Install JDK (We recommend Azul Zulu JDK 17 on macOS, and Temurin elsewhere). 2. Install `sbt`, following . sbt acts as a package manager, so once you installed JDK and sbt, it will download necessary dependencies. diff --git a/contributing-docs/99_hints.md b/contributing-docs/99_hints.md new file mode 100644 index 000000000..c18be0088 --- /dev/null +++ b/contributing-docs/99_hints.md @@ -0,0 +1,45 @@ +Random tidbits +============== + +### 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). + +1. Install the current stable binary release of sbt (see [Setup]), which will be used to build sbt from source. +2. Get the source code. + + ```bash + $ 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 + ``` + +3. To build and publish all components locally, + + ```bash + $ ./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. + + + +### Import statements + +You'd need alternative DSL import since you can't rely on sbt package object. + +```scala +// for slash syntax +import sbt.SlashSyntax0.given + +// for IO +import sbt.io.syntax.* +``` diff --git a/contributing-docs/README.md b/contributing-docs/README.md index 676094067..3c0c17155 100644 --- a/contributing-docs/README.md +++ b/contributing-docs/README.md @@ -1,5 +1,3 @@ -Contributor's guide -=================== Contributions are welcome and are greatly appreciated! There are lots of avenues to contribute to the sbt ecosystem, depending on your interests and skill level. @@ -26,7 +24,7 @@ See [CONTRIBUTING](../CONTRIBUTING.md). Patching the core (sending pull request) ---------------------------------------- -See [pull request](01_pull_request.md) +See [CONTRIBUTING](../CONTRIBUTING.md). [documentation]: https://github.com/sbt/website [Discord]: https://discord.com/invite/scala