spring-cloud-commons: the shared layer under the Spring Cloud train

Where the common classes actually live

spring-cloud-commons is described as the common classes used in different Spring Cloud implementations, and the repository layout shows the shape of that.

The main code modules are spring-cloud-context, which holds the shared context support, and spring-cloud-loadbalancer, which holds the load balancing code. Around them sit the artifacts an application actually depends on: spring-cloud-starter, spring-cloud-starter-bootstrap, and spring-cloud-starter-loadbalancer, along with spring-cloud-commons-dependencies, which is the dependency management module for the train.

Then there is the test surface. spring-cloud-test-support exists so that the components in the train can be tested against each other, and there are two dedicated integration test modules, spring-cloud-context-integration-tests and spring-cloud-context-webflux-integration-tests, which tells you that both the servlet and the reactive stacks are covered.

The licence is Apache-2.0, the language is Java, and the repository is not archived. The release tags follow the train's version scheme, with v5.0.3 from 2026-08-20 and the v5.1.0-M1 milestone from 2026-09-24.

The point of the repository is consolidation. When several Spring Cloud implementations need the same behaviour, it belongs here rather than being copied into each one, which is why the load balancer in particular sits in commons rather than in a single provider.

Reading a README that is generated from asciidoc

The README of this repository opens with a warning worth taking seriously: do not edit this file, it was generated, manual changes will be lost when it is generated again, and the files in the src/main/asciidoc directory are the ones to edit instead.

That is the documentation pipeline in one paragraph. The project documents itself in asciidoc under src/main/asciidoc, the build copies those sources into a README.adoc, and the file you are reading on GitHub is an artefact. It is the same pattern the project uses for its published documentation, which is built with Antora from the modules/ROOT directory when the docs profile is enabled.

Two practical consequences. If you want to fix a typo in the README, you are editing the wrong file and your change will vanish at the next build. And if you want to understand the project's own conventions, the README is the canonical place for them, because the same asciidoc feeds both the repository page and the documentation site.

The README also carries the release train settings, since the file release-train-settings.xml sits at the repository root and the documentation refers to a spring-cloud-build-branch variable set to main.

Building: JDK 17, the Maven wrapper and the spring profile

The build section is short and assumes some experience with Maven projects. You need to install JDK 17, and Spring Cloud uses Maven for most build-related activities, so cloning and typing the following is the shortest route to a working build:

$ ./mvnw install

If you would rather install Maven yourself, the README says you can use the mvn command in place of ./mvnw, but with two caveats. You need Maven 3.3.3 or newer, and if your local settings do not contain repository declarations for the spring pre-release artifacts you may need to add the -P spring profile.

That profile requirement is the one that catches people out. Spring Cloud projects require the spring Maven profile to be activated in order to resolve the spring milestone and snapshot repositories, and the README warns twice: set the profile active in your IDE or you may experience build errors. The same advice is repeated in the Eclipse section, where an older m2e that does not support Maven 3.3 requires you to add the spring profile to your settings.xml or copy the repository settings from the spring profile of the parent pom.

There is also a memory note. You might need to increase the memory available to Maven by setting a MAVEN_OPTS environment variable with a value like -Xmx512m -XX:MaxPermSize=128m. The project says it tries to cover this in the .mvn configuration, and if a build still fails you are asked to raise a ticket so the settings can be added to source control.

The docs profile and the Antora site

The spring-cloud-build module has a docs profile, and enabling it makes the build try to build the asciidoc sources using Antora from the modules/ROOT directory.

The mechanism has a detail that explains why the README looks the way it does. During that process the build looks for a docs/src/main/asciidoc/README.adoc and processes it by loading all the includes, but not parsing or rendering it, just copying it to the main basedir, which defaults to the project root. Any change in the README then shows up after a Maven build as a modified file in the right place, and you commit and push it.

So the repository README and the documentation site share a source of truth, and the copy is deliberate rather than an accident of the build.

The site itself is generated with one command:

./mvnw -pl docs -P docs antora:antora

The build documentation is written in asciidoc with Antora attributes, and the doc directory at the repository root is the visible part of that pipeline. For contributors who want to see what a change looks like, this is the command to run, and the same asciidoc that produces the repository README produces the published pages.

Tests that need Redis, and the Docker requirement

The build section has one line that tells you what a contributor needs beyond a JDK, and it is easy to skim past.

The projects that require middleware, with Redis given as the example, generally require that a local instance of Docker is installed and running. That is a hard requirement for the integration test modules rather than a suggestion, since the context and webflux integration test modules exercise code that talks to a real Redis instance.

The practical consequence for a contributor is that a green unit test run is not the same as a green build. If Docker is not running, the middleware-dependent tests will not pass, and the failure looks like a code problem when it is an environment problem.

This is also why the repository ships two separate integration test modules rather than folding them into the main modules. Keeping the context integration tests and the context webflux integration tests apart means the slow, dependency-heavy parts of the suite are isolated, and the reactive and servlet variants can evolve separately as the two stacks diverge.

The spring-cloud-test-support module exists for the same reason. When a component in the train needs to be exercised against another component in the train, that shared harness has to live somewhere both can depend on.

Contribution mechanics: DCO, formatting and checkstyle

Spring Cloud is released under the non-restrictive Apache 2.0 license and follows a very standard GitHub development process, using the GitHub tracker for issues and merging pull requests into main.

The contribution requirement that catches newcomers is the Developer Certificate of Origin. All commits must include a Signed-off-by trailer at the end of each commit message to indicate that the contributor agrees to the DCO, and the README links a post titled Hello DCO, Goodbye CLA about simplifying contributions to Spring. This replaced the old Contributor License Agreement requirement, so the ask is a sign-off line rather than a signed legal document.

The code conventions section is more prescriptive. Use the Spring Framework code format conventions, which you can import in Eclipse from the eclipse-code-formatter.xml file in the Spring Cloud Build project, or in IntelliJ with the Eclipse Code Formatter plugin. New .java files need a simple Javadoc class comment with at least an @author tag, and preferably a paragraph on what the class is for, plus the ASF license header comment copied from existing files. If you modify a file substantially rather than cosmetically, add yourself as an @author. A few unit tests would help.

The checkstyle rules live in the spring-cloud-build-tools module, and the README points at the most notable files there, so the enforcement is a project-wide configuration rather than a per-repository one.

Editorial conclusion

Use spring-cloud-commons if you are extending a Spring Cloud component, contributing a shared class back to the train, or building the train itself from source to match a Spring Boot version you are not yet able to take from a release. Do not adopt it as an application dependency in the hope of getting features early, since the artifacts on Maven Central already carry the same classes, and do not start a build without JDK 17, Maven 3.3.3 or newer and Docker for the tests that need Redis. Before you build, read the spring profile instructions, since resolving milestone and snapshot repositories is the step that most often breaks a fresh checkout, and note that the latest releases are v5.0.3 from 2026-08-20 and the milestone v5.1.0-M1 from 2026-09-24, with the last push on 2026-10-15.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. spring-cloud/spring-cloud-commons on GitHub