diff --git a/.github/ISSUE_TEMPLATE/config.yml b/.github/ISSUE_TEMPLATE/config.yml new file mode 100644 index 00000000..3dee38ee --- /dev/null +++ b/.github/ISSUE_TEMPLATE/config.yml @@ -0,0 +1,5 @@ +blank_issues_enabled: false +contact_links: + - name: Community Support + url: https://stackoverflow.com/tags/spring-data + about: Please ask and answer questions on StackOverflow with the tag `spring-data`. diff --git a/.github/ISSUE_TEMPLATE/issue.md b/.github/ISSUE_TEMPLATE/issue.md new file mode 100644 index 00000000..a7c70af6 --- /dev/null +++ b/.github/ISSUE_TEMPLATE/issue.md @@ -0,0 +1,36 @@ +--- +name: General issue +about: Bugs, enhancements, documentation, tasks. +title: '' +labels: '' +assignees: '' +--- + + diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index fddac5c7..299f0385 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -1,12 +1,40 @@ +Please submit only genuine pull-requests. Do not use this repository as a GitHub +playground. + +Security Vulnerabilities + +🛑 STOP! If your contribution fixes a security vulnerability, please do not submit it. +Instead, please head over to https://spring.io/security-policy to learn how to disclose a +vulnerability responsibly. + +Dependency Upgrades -- [ ] You have read the [Spring Data contribution guidelines](https://github.com/spring-projects/spring-data-build/blob/master/CONTRIBUTING.adoc). -- [ ] You use the code formatters provided [here](https://github.com/spring-projects/spring-data-build/tree/master/etc/ide) and have them applied to your changes. Don’t submit any formatting related changes. -- [ ] You submit test cases (unit or integration tests) that back your changes. -- [ ] You added yourself as author in the headers of the classes you touched. Amend the date range in the Apache license header if needed. For new types, add the license header (copy from another file and set the current year only). +Please do not open a pull request for a straightforward dependency upgrade (one that +only updates the version property). We have a semi-automated process for such upgrades +that we prefer to use. However, if the upgrade is more involved (such as requiring +changes for removed or deprecated API) your pull request is most welcome. +Describing Your Changes + +If, having reviewed the notes above, you're ready to submit your pull request, please +provide a brief description of the proposed changes. If they fix a bug, please +describe the broken behaviour and how the changes fix it. If they make an enhancement, +please describe the new functionality and why you believe it's useful. If your pull +request relates to any existing issues, please reference them by using the issue number +prefixed with #. + +A brief description of what else to consider, make sure that: +- You have read the [Spring Data contribution guidelines](https://github.com/spring-projects/spring-data-build/blob/master/CONTRIBUTING.adoc). +- You use the code formatters provided [here](https://github.com/spring-projects/spring-data-build/tree/master/etc/ide) and have them applied to your changes. +Don’t submit any formatting related changes. +- You submit test cases (unit or integration tests) that back your changes. +- You added yourself as author in the headers of the classes you touched. +Amend the date range in the Apache license header if needed. For new types, add the license header (copy from another file and set the current year only). +- Your commits include a Signed-off-by trailer at the end of each commit message to indicate that the contributor agrees to the Developer Certificate of Origin. + +--> diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 00000000..a790d1ac --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,27 @@ +This is a Framework project. We welcome contributions that serve developer productivity and code quality supporting common use-cases instead of one-off customizations. +Explain that AI-generated contributions may be labelled as AI slop if the usage of AI leads to low-quality contributions lead to maintainers do busy-work do read lengthy and low-quality descriptions. +The more effort a contributor puts into understanding the problem and crafting a concise description, the better the chances of a successful contribution. + +## Issues + +- For non-trivial issues, include a link to a sample project that reproduces the issue. +- Assume all versions to be that of the latest release. Only specify versions that deviate from that. +- Specify dependencies only if the problem exists for one version or variant, but not for others. +- Don't repeat information specified in the reference reproducer. +- Be specific and concise, avoiding being unnecessary verbose. Avoid summarization and bullet-point lists unless absolutely necessary. +- Add `Issue created by AI` to the issue description. + +## Pull requests + +- If there is an issue that gets fixed by this PR, add the keyword `Closes #` to the PR description. +- Add `PR created by AI` to the PR description. +- If the change is not trivial, make sure there exists an issue for it. +- Make the description short. +- Do not repeat information. +- Avoid superfluous embellishments. +- Use formatting sparingly. +- Do not repeat information contained in the issue description. +- Make sure the PR builds successfully, including tests. +- Make sure the PR contains tests for changed behavior. +- Make sure the contributor has understood the changes and their implications instead of just committing the output of an AI tool. +- Make sure the PR adheres to the contribution guidelines: https://github.com/spring-projects/spring-data-build/blob/main/CONTRIBUTING.adoc. diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 00000000..a790d1ac --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,27 @@ +This is a Framework project. We welcome contributions that serve developer productivity and code quality supporting common use-cases instead of one-off customizations. +Explain that AI-generated contributions may be labelled as AI slop if the usage of AI leads to low-quality contributions lead to maintainers do busy-work do read lengthy and low-quality descriptions. +The more effort a contributor puts into understanding the problem and crafting a concise description, the better the chances of a successful contribution. + +## Issues + +- For non-trivial issues, include a link to a sample project that reproduces the issue. +- Assume all versions to be that of the latest release. Only specify versions that deviate from that. +- Specify dependencies only if the problem exists for one version or variant, but not for others. +- Don't repeat information specified in the reference reproducer. +- Be specific and concise, avoiding being unnecessary verbose. Avoid summarization and bullet-point lists unless absolutely necessary. +- Add `Issue created by AI` to the issue description. + +## Pull requests + +- If there is an issue that gets fixed by this PR, add the keyword `Closes #` to the PR description. +- Add `PR created by AI` to the PR description. +- If the change is not trivial, make sure there exists an issue for it. +- Make the description short. +- Do not repeat information. +- Avoid superfluous embellishments. +- Use formatting sparingly. +- Do not repeat information contained in the issue description. +- Make sure the PR builds successfully, including tests. +- Make sure the PR contains tests for changed behavior. +- Make sure the contributor has understood the changes and their implications instead of just committing the output of an AI tool. +- Make sure the PR adheres to the contribution guidelines: https://github.com/spring-projects/spring-data-build/blob/main/CONTRIBUTING.adoc. diff --git a/CONTRIBUTING.adoc b/CONTRIBUTING.adoc index f4023c5b..2df58d09 100644 --- a/CONTRIBUTING.adoc +++ b/CONTRIBUTING.adoc @@ -2,6 +2,7 @@ First off, thank you for taking the time to contribute! 👍 🎉 + [[code-of-conduct]] == Code of Conduct @@ -11,26 +12,25 @@ Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. [[using-github-issues]] == Using GitHub Issues + We use GitHub issues to track bugs and enhancements. -If you have a general usage question please ask on https://stackoverflow.com[Stack Overflow]. +If you have a general usage question, please ask on https://stackoverflow.com[Stack Overflow]. The Spring Data team and the broader community monitor the https://stackoverflow.com/tags/spring-data[`spring-data`] tag. If you are reporting a bug, please help to speed up problem diagnosis by providing as much information as possible. -Ideally, that would include a small sample project that reproduces the problem. +For non-trivial bugs provide a [Minimimal Reproducable Example](https://stackoverflow.com/help/minimal-reproducible-example), preferable as a GitHub repository. Make sure to include the database, either as an in memory database or if that is not possible using [Testcontainers](https://www.testcontainers.org/). +The preferred build tool is Maven. +The preferred language is Java. +[[security-vulnerabilities]] == Reporting Security Vulnerabilities -If you think you have found a security vulnerability in Spring Data please *DO NOT* disclose it publicly until we've had a chance to fix it. + +If you think you have found a security vulnerability in Spring Data, please *DO NOT* disclose it publicly until we've had a chance to fix it. Please don't report security vulnerabilities using GitHub issues, instead head over to https://spring.io/security-policy and learn how to disclose them responsibly. [[how-to-contribute]] == How to Contribute -[[security-vulnerabilities]] -=== Reporting Security Vulnerabilities - -If you think you have found a security vulnerability in Spring Data please **DO NOT** disclose it publicly until we’ve had a chance to fix it. -Please don’t report security vulnerabilities using GitHub issues, instead head over to https://pivotal.io/security and learn how to disclose them responsibly. - [[discuss]] === Discuss @@ -47,10 +47,10 @@ For the impatient, if you want to submit a quick pull request (polishing, trivia 1. API changes require discussion, use cases, etc. Code comes later. -Create a issue in the GitHub issue tracker and stop here. +Create an issue in the GitHub issue tracker and stop here. In every other case continue with step 2. 2. Make sure you use the code formatters provided https://github.com/spring-projects/spring-data-build/tree/main/etc/ide[here] and have them applied to your changes. -Don't submit any formatting related changes. +Don't submit any formatting-related changes. 3. Make sure you submit test cases (unit or integration tests) that back your changes. 4. Try to reuse existing test sample code (domain classes). Try not to amend existing test cases but create new ones dedicated to the changes you're making to the codebase. @@ -64,7 +64,7 @@ void yourTestMethod() { … } ---- + 6. Make sure you added yourself as author in the headers of the classes you touched. -Amend the date range in the Apache license header if needed. +Amend the date range in the Apache License header if needed. For new types, add the license header (copy from another file and set the current year only). 7. Make sure you follow the <> guidelines. 8. Make sure you provide your full name and an email address registered with your GitHub account. @@ -95,8 +95,8 @@ For more details read https://asciidoctor.org/docs/editing-asciidoc-with-live-pr The commit message should follow the following style: -* First line contains the summary starting with a capital letter. -* Finish summary with a dot. +* The first line contains the summary starting with a capital letter. +* Finish the summary with a dot. * In the description, don't use single line breaks. No manual wrapping. Separate paragraphs by a blank line. @@ -115,6 +115,23 @@ Closes #?? (optionally close tickets) Related tickets #??? (optionally refer to related tickets) ---- +=== Use of AI + +LLM's have an answer to almost every input. +With the emergence of AI, we are evaluating the value of contributions that were created with the help of AI. +It is not about generating code, we can craft a prompt ourselves after all. +It is about nuanced balancing of implications and deep understanding of the problem at hand that eventually can result in creating +code. +We (hopefully) can't tell the difference anyway. +You are still responsible for everything you commit, push, submit, or otherwise contribute to this project, including that you have not infringed any copyrights. + +Unfortunately, we lately encountered an increased amount of high-content low-quality contributions that is considered AI slop. +Descriptions that could have been a few sentences stretched for pages and pages. +Sifting through such prose to find the relevant information is extremely tiring and frustrating. + +We will close and reject such contributions with a simple comment and will not engage in further discussion. +You may, however, create a new PR or issue in a terser format. + [[advanced]] == Advanced @@ -123,17 +140,18 @@ This section contains some advanced information, mainly targeted at developers o [[advanced.general]] === General -* Fix bugs in main first, if it's reasonable to port the fix back into a bugfix branch, try to do so with cherry picking. +* Fix bugs in `main` first, if it's reasonable to port the fix back into a bugfix branch, try to do so with cherry-picking. * Try to keep the lifespan of a feature branch as short as possible. For simple bug fixes they should only be used for code review in pull requests. -* On longer running feature branches, don't pull changes that were made to main in the meantime. -Instead, rebase the feature branch onto current main, sorting out issues and making sure the branch will fast-forward merge eventually. +* On longer running feature branches, don't pull changes that were made to `main` in the meantime. +Instead, rebase the feature branch onto the current `main`, sorting out issues and making sure the branch will fast-forward merge eventually. [[advanced.dependency-management]] === Dependency management * When upgrading dependencies of a project, make sure you apply the following rules: -** For service releases of a release train only upgrades to bugfix versions are allowed. I.e. if a GA release of a release train included a dependency in version 2.6.2, you must only upgrade to 2.6.x versions. +** For service releases of a release train, only upgrades to bugfix versions are allowed. +I.e., if a GA release of a release train included a dependency in version 2.6.2, you must only upgrade to 2.6.x versions. Upgrading to 2.7 is *not allowed*. ** During the milestone phase of a new release train, upgrade to the latest version of a dependency unless compatibility with a former version is required. Upgrades to new major versions are allowed, too, but consider ways to support multiple major versions for one release train to allow a smoother transition. @@ -143,12 +161,13 @@ Upgrades to new major versions are allowed, too, but consider ways to support mu We use JMH for micro-benchmarks. -Our benchmarks are located in the `src/jmh/java` directory so that we compile these as part of our main build. To run benchmarks during development we leverage JUnit 5 and the https://github.com/mp911de/microbenchmark-runner[Microbenchmark Runner]. +Our benchmarks are located in the `src/jmh/java` directory so that we compile these as part of our main build. +To run benchmarks during development, we leverage JUnit and the https://github.com/mp911de/microbenchmark-runner[Microbenchmark Runner]. Enable the `jmh` Maven Profile, add `@Testable` to the benchmark you want to run (of the benchmark class) and run it as it was a JUnit test right from your IDE. NOTE: Microbenchmark Runner is not a tool for running final benchmarks, rather it helps to quickly run benchmarks during development to reduce turnaround time. -Benchmarks aren't ran during the build. +Benchmarks aren't run during the build. JMH's Benchmark Generator (Annotation Processor) must be enabled in each module with the Maven Compiler, see the following example: @@ -178,18 +197,19 @@ Once the issue has been reviewed, the team may ask for further information if ne When a fix is ready, the issue is closed and may still be re-opened until the fix is released. After that the issue will typically no longer be reopened. In rare cases if the issue was not at all fixed, the issue may be re-opened. -In most cases however any follow-up reports will need to be created as new issues with a fresh description. +In most cases, however, any follow-up reports will need to be created as new issues with a fresh description. * Make sure you don't commit without referring to a GitHub issue. If we have a rather general task to work on, create a GitHub issue for it and commit against that one. -* Try to resolve a GitHub issue in a single commit. I.e. don't have separate commits for the fix and the test cases. +* Try to resolve a GitHub issue in a single commit. +I.e., don't have separate commits for the fix and the test cases. When polishing pull requests requires some more effort, have a separate commit to clearly document the polishing (and attribute the efforts to you). * We usually use feature branches to work on GitHub issues and potentially let multiple people work on a feature. -There's a https://github.com/spring-projects/spring-data-build/tree/main/etc/scripts[new-issue-branch script] available that sets up a feature branch for you, and adds a commit changing the Maven version numbers so that the branch builds can still publish snapshot artifacts but don't interfere with each other. +There's a https://github.com/spring-projects/spring-data-build/tree/main/etc/scripts[new-issue-branch script] available that sets up a feature branch for you and adds a commit changing the Maven version numbers so that the branch builds can still publish snapshot artifacts but don't interfere with each other. * Follow the commit message style described in <>. Especially the summary line should adhere to the style documented there. * After pushing fixes to the remote repository, mark the GitHub issues as resolved in and set the earliest milestone that ships the fix according to which branches you pushed to. * Avoid merge commits as they just tend to make it hard to understand what comes from where. -Using the GitHub issue number in the commit message will allow us to keep track for commits belonging together. +Using the GitHub issue number in the commit message will allow us to keep track of commits belonging together. [[advanced.code-style]] === Source Code style @@ -206,14 +226,14 @@ For methods consisting of more than one line of code, have a blank line after th === Handling pull requests * Be polite. -It might be the first time someone contributes to an OpenSource project so we should forgive violations to the contribution guidelines. +It might be the first time someone contributes to an OpenSource project, so we should forgive violations to the contribution guidelines. Use some gut feeling to find out in how far it makes sense to ask the reporter to fix stuff or just go ahead and add a polishing commit yourself. * All commits must include a __Signed-off-by__ trailer at the end of each commit message to indicate that the contributor agrees to the Developer Certificate of Origin. For additional details, please refer to the blog post https://spring.io/blog/2025/01/06/hello-dco-goodbye-cla-simplifying-contributions-to-spring[Hello DCO, Goodbye CLA: Simplifying Contributions to Spring]. Signing the contributor’s agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. If you forget to do so, you'll be reminded when you submit a pull request. * Before merging stuff back into `main`, make sure you rebase the branch. -We generally do not allow merge commits, so a merge should always be fast-forward. +We generally do not allow merge commits, so a merge should always be fast-forwarded. The GitHub issue number and the timestamps give enough tracking information already. * The simplest way to merge back a pull request submitted by someone external is ``curl``ing the patch into `git am`. You can then polish it by either adding a commit or amending the provided commit. @@ -224,10 +244,10 @@ Make sure you keep the original author when amending. curl $PULL_REQUEST_URL.patch | git am --ignore-whitespace ---- -* If you merge back a feature branch and multiple developers contributed to that, try to rearrange to commits and squash the into a single commit per developer. +* If you merge back a feature branch and multiple developers contributed to that, try to rearrange to commits and squash them into a single commit per developer. Combine the commit messages and edit them to make sense. * Before pushing the changes to the remote repository, amend the commit(s) to be pushed and add a reference to the pull request to them. -This will cause the pull request UI in GitHub show and link those commits. +This will cause the pull request UI in GitHub to show and link those commits. [source] ---- diff --git a/parent/pom.xml b/parent/pom.xml index 7e69f7f7..e38c6bf6 100644 --- a/parent/pom.xml +++ b/parent/pom.xml @@ -26,7 +26,7 @@ org.springframework.data.build spring-data-build - 4.1.0-SNAPSHOT + 4.1.0-9999-SNAPSHOT ../pom.xml @@ -496,7 +496,7 @@ org.springframework.data.build spring-data-build-resources - 4.1.0-SNAPSHOT + 4.1.0-9999-SNAPSHOT zip true @@ -798,7 +798,7 @@ org.springframework.data.build spring-data-build-resources - 4.1.0-SNAPSHOT + 4.1.0-9999-SNAPSHOT zip true diff --git a/pom.xml b/pom.xml index 9ddf1d05..9d2327e1 100644 --- a/pom.xml +++ b/pom.xml @@ -4,7 +4,7 @@ 4.0.0 org.springframework.data.build spring-data-build - 4.1.0-SNAPSHOT + 4.1.0-9999-SNAPSHOT pom Spring Data Build diff --git a/resources/pom.xml b/resources/pom.xml index 8d722ec2..c73e8bb2 100644 --- a/resources/pom.xml +++ b/resources/pom.xml @@ -8,7 +8,7 @@ org.springframework.data.build spring-data-build - 4.1.0-SNAPSHOT + 4.1.0-9999-SNAPSHOT ../pom.xml