Contributing and Development Workflow

Relevant source files

• .github/PULL_REQUEST_TEMPLATE.md
• CONTRIBUTING.adoc
• README.adoc
• SUPPORT.adoc
• eclipse/spring-boot-project.setup
• git/hooks/prepare-forward-merge

This page covers the process for contributing code and reporting issues to the Spring Boot project. It addresses the policies, tooling, and git workflow that a contributor must follow from first contact through to a merged pull request.

For information about IDE setup and importing the project into Eclipse or IntelliJ, see IDE Setup and Configuration. For information about the Checkstyle and code quality tooling that enforces these conventions at build time, see Checkstyle and Kotlin Conventions.

---

Contribution Flow Overview

Contribution lifecycle: from issue to merge

Sources: CONTRIBUTING.adoc1-64 README.adoc64-83 .github/PULL_REQUEST_TEMPLATE.md1-30

---

Code of Conduct

The project adheres to the Contributor Covenant code of conduct. Unacceptable behavior should be reported to [email protected]. The code of conduct file is linked directly from the repository's GitHub tab (coc-ov-file).

Sources: CONTRIBUTING.adoc7-10

---

Issue Tracking

Spring Boot uses GitHub Issues exclusively for bugs and enhancements. The following table describes the correct channel for each type of inquiry:

Situation	Channel
General usage question	Stack Overflow, spring-boot tag
Bug report or feature request	GitHub Issues
Security vulnerability	https://spring.io/security-policy
Enterprise support needs	VMware Tanzu Enterprise Support

When filing a bug, the report should include:

• Spring Boot version
• Operating system and JVM version
• A small sample project that reproduces the problem
• Stack traces formatted as Markdown code blocks

Do not open a pull request for a straightforward dependency version bump. The project uses a semi-automated upgrade process for those. PRs that make API-level changes alongside a version upgrade are welcome.

Sources: CONTRIBUTING.adoc14-29 README.adoc71-83 SUPPORT.adoc1-30 .github/PULL_REQUEST_TEMPLATE.md1-30

---

Developer Certificate of Origin (DCO)

All commits must contain a Signed-off-by trailer at the end of the commit message. This replaced the previous CLA process in January 2025.

Your commit message here

Signed-off-by: Your Name <[email protected]>

The git commit -s flag appends this trailer automatically. The requirement applies to every commit in a pull request, not just the merge commit.

Sources: CONTRIBUTING.adoc32-36

---

Code Formatting and Conventions

Tooling involved in code quality enforcement

Sources: CONTRIBUTING.adoc39-58 eclipse/spring-boot-project.setup67-98

The full set of conventions required for a pull request:

Convention	How to apply
Code formatting	./gradlew format or Eclipse/IntelliJ plugin
buildSrc formatting	./gradlew -p buildSrc format
Checkstyle compliance	./gradlew checkstyleMain checkstyleTest
All verification	./gradlew check
New .java files	Add ASF license header; add @author tag in Javadoc
Modified .java files	Add @author if changes are substantial
Commit message format	Follow Tim Pope's conventions (imperative, 50-char subject, wrapped body)

Note: The SPRING_PROFILES_ACTIVE environment variable can affect test results. Run unset SPRING_PROFILES_ACTIVE before executing ./gradlew check to avoid interference.

Sources: CONTRIBUTING.adoc39-58

---

Pull Request Template

The file .github/PULL_REQUEST_TEMPLATE.md1-30 guides contributors when opening a pull request. The key points it enforces:

• Security vulnerabilities must not be submitted as PRs — use spring.io/security-policy instead.
• Straightforward dependency upgrades (version property only) should not be submitted as PRs.
• All other PRs should include: a description of the change, an explanation of why (bug fix behavior, new functionality rationale), and references to existing GitHub issues using #<number> syntax.

---

Git Commit Message Conventions

The project follows the conventions described at tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html. In summary:

• Subject line: imperative mood, no period, max ~50 characters
• Body: wrapped at 72 characters
• Reference issues with Fixes gh-<number> or Closes gh-<number>
• End with the Signed-off-by trailer

---

Forward-Merge Git Hook

The repository includes a prepare-commit-msg hook at git/hooks/prepare-forward-merge1-72 This hook is used by maintainers when merging older release branches forward into newer ones (e.g., 3.4.x → 4.0.x → main).

How the prepare-forward-merge hook works

The hook:

1. Reads MERGE_HEAD to find what commit is being merged in.
2. Scans the incoming commit's message for lines matching ^(?:Fixes|Closes) gh-(\d+).
3. Rewrites the merge commit subject to strip remote-tracking prefixes (e.g., turns origin/3.4.x into 3.4.x).
4. Injects Fixes gh-<N> in <current_branch> annotations before the first git comment line (#), so the issue closure is recorded on the target branch.

The variable $main_branch at git/hooks/prepare-forward-merge7 is set to the current main development branch (currently "4.1.x"). When HEAD is main, the hook substitutes $main_branch in the annotation.

To install this hook, copy or symlink git/hooks/prepare-forward-merge to .git/hooks/prepare-commit-msg in your local checkout.

Sources: git/hooks/prepare-forward-merge1-72

---

Building from Source

To build all modules and publish them to the local Maven cache without running tests:

To run the full build including all tests:

A JDK 25 installation is required. The Gradle wrapper (gradlew) handles downloading the correct Gradle version automatically.

For more detail on the build system itself — including buildSrc conventions, settings.gradle, and how dependency versions flow through the BOM — see Build System and Dependency Management.

Sources: README.adoc86-104

---

Key Files Reference

File	Purpose
CONTRIBUTING.adoc	Primary contributor guidelines
README.adoc	Project overview; issue reporting and build instructions
SUPPORT.adoc	Support channel descriptions
.github/PULL_REQUEST_TEMPLATE.md	PR submission checklist shown in GitHub UI
git/hooks/prepare-forward-merge	Commit message rewriting hook for forward merges
eclipse/spring-boot-project.setup	Oomph setup file for Eclipse contributors

Sources: CONTRIBUTING.adoc1-64 README.adoc1-120 SUPPORT.adoc1-30 .github/PULL_REQUEST_TEMPLATE.md1-30 git/hooks/prepare-forward-merge1-72 eclipse/spring-boot-project.setup1-431