Working with the Code

See the CONTRIBUTING file in the repository for information on how to contribute issues and code changes to the project.

Building from Source

Spring Vault source can be built from the command line using Maven. We include Maven’s wrapper scripts (./mvnw or mvnw.cmd) that you can run rather than needing to install Maven locally.

The source on the main branch and all 4.x and 3.x branches should be built with JDK 17. The 2.x branches need JDK 8 and the 1.x branches JDK 6. CI builds each branch against its baseline JDK and against a more recent JDK.

The project can be built from the root directory using the standard Maven command:

$ ./mvnw install

./mvnw test runs the unit tests (*UnitTests) only. ./mvnw verify and ./mvnw install also run the integration tests (*IntegrationTests), which require a Vault server as described below. Use -DskipTests to skip all tests.

Tests Requiring a Vault Server

The integration tests run against a Vault server listening on https://localhost:8200 with TLS enabled. They fail if no server is available, they are not skipped automatically. The scripts in src/test/bash download Vault, create the certificates, and start the server:

$ ./src/test/bash/start.sh

start.sh runs the following scripts in order and leaves Vault running in the background:

install_vault.sh downloads Vault into vault/ (downloads are cached in download/). Set VAULT_OSS to pick a specific version, or EDITION=ent together with VAULT_ENT to test against Vault Enterprise.
create_certificates.sh creates a CA and a server certificate in work/ca and a JKS truststore in work/keystore.jks (password changeit).
local_run_vault.sh starts Vault with src/test/bash/vault.conf using the generated certificates.

Vault starts sealed and uninitialized. The test support (VaultInitializer) initializes and unseals Vault, mounts the secrets engines the tests need, and obtains a root token, so no manual vault operator init is required. To use the Vault CLI against the test server, source src/test/bash/env.sh, which exports VAULT_ADDR, VAULT_TOKEN, and VAULT_CAPATH.

Some tests are skipped unless their environment is available:

Tests for Vault Enterprise features (namespaces, Transform secrets engine) are skipped when the server is not an enterprise build.
Tests annotated with @RequiresVaultVersion or @DisabledOnVaultVersion are skipped depending on the version of the running server.
Kubernetes authentication tests require Minikube and are skipped unless the MINIKUBE_IP system property is set. See local_run_k8s.sh and minikube_ci_initialize.sh for the setup used on CI.

Building on Windows

The Vault scripts require a *NIX-like environment with curl, openssl, and unzip. On Windows, use the Windows Subsystem for Linux (WSL) and share JAVA_HOME between WSL and Windows by running the following command in PowerShell:

$ setx WSLENV "JAVA_HOME/p"

Updating the Reference Documentation

The reference documentation is stored in this repository, see src/main/antora. We use Antora with Asciidoc and you can build the documentation locally using this command:

$ ./mvnw -Pantora -pl spring-vault-distribution antora

Note	The generated HTML documentation is available from `spring-vault-distribution/target/antora/site/`.

See Antora for details on the documentation structure, the extensions in use, and how the production site is built and published.

Using an IDE

We want Spring Vault to work well with any IDE, and we are especially invested in IntelliJ IDEA and Eclipse. The code is formatted with the Spring Framework formatter settings in etc/ide (formatter.xml and eclipse.importorder). Both setups below apply them automatically.

Importing into IntelliJ IDEA

The repository contains a .idea folder with useful settings such as code style, copyright headers, and the Eclipse Code Formatter configuration. These are taken into account automatically.

If you have performed a checkout of this repository already, use “File” → “Open” and then select the root pom.xml file to import the code.

Alternatively, you can let IntelliJ IDEA checkout the code for you. Use “File” → “New” → “Project from Version Control” and https://github.com/spring-projects/spring-vault for the URL. Once the checkout has completed, a pop-up will suggest to open the project.

Install the Eclipse Code Formatter plugin

Install the Adapter for Eclipse Code Formatter plugin so that the project formatting rules are applied when you reformat code in the IDE. The plugin picks up the committed configuration in .idea/eclipseCodeFormatter.xml, which points to etc/ide/formatter.xml and etc/ide/eclipse.importorder.

Importing into Eclipse

We use the m2e Eclipse plugin for Maven support. If you don’t already have m2e installed it is available from the “Eclipse marketplace”.

Select Maven → Existing Maven Projects from the File → Import… menu to import the code.

Then apply the project formatting settings:

Select “Preferences” → “Java” → “Code Style” → “Formatter” and import etc/ide/formatter.xml.
Select “Preferences” → “Java” → “Code Style” → “Organize Imports” and import etc/ide/eclipse.importorder.
Enable “Save Actions” to format sources and organize imports on save.

Importing into Other IDEs

Maven is well supported by most Java IDEs. Refer to your vendor documentation.

Git Conventions

Spring Vault follows the Spring Data conventions for branches, commits, and pull requests. They differ from the Spring Boot conventions in a few places, which are called out below.

Branches

The main branch contains the upcoming minor or major version of Spring Vault. Maintenance branches are named <major>.<minor>.x (for example 4.1.x) and exist for all supported versions. Work in progress on an issue happens on issue/<number> branches, CI builds these branches as well.

Fixes are applied to main first and then back-ported to the affected maintenance branches by cherry-picking the commit. Unlike Spring Boot, Spring Vault does not merge maintenance branches forward and does not use merge commits, the history of every branch is linear.

$ git checkout main
$ git pull
# apply and commit the fix
$ git push
$ git checkout 4.1.x
$ git pull
$ git cherry-pick <SHA>
$ git push

A single GitHub issue tracks a change across all branches. Every commit references that issue, and the issue is assigned to the milestone of the earliest release that ships the fix. No separate back-port issues are created.

Commit Messages

Commit messages follow the Spring Data style:

The summary line starts with a capital letter, uses the imperative mood, stays under 80 characters, and ends with a period (Spring Boot omits the period).
Separate the summary from the body with a blank line. Don’t wrap lines in the body manually, separate paragraphs by a blank line.
Every commit references a GitHub issue or pull request at the very bottom of the message using Closes #123 or See #123. Older commits use the gh-123 form.
Contributed changes keep the contributor as the author and reference the pull request with Original pull request: #123.
Polishing commits use the summary Polishing. and reference the issue with See #123.
Contributions must carry a Signed-off-by trailer, see the CONTRIBUTING file.

A typical commit:

Use set-based lookups for `IN` and `NOT_IN` query predicates.

Closes #999

A polishing commit on top of a contribution:

Polishing.

Use Map.copyOf(…) instead of Collections.unmodifiableMap(new LinkedHashMap<>(…)).

See #999
Original pull request: #1000

Releases produce a Release Spring Vault 4.1.0. commit (Closes #<release issue>) followed by Prepare next development iteration. (See #<release issue>).

Pull Requests

Pull requests are not merged through the GitHub UI and never produce a merge commit. The maintainer applies the patch on top of the target branch, keeping the contributor as the author:

$ curl https://github.com/spring-projects/spring-vault/pull/1000.patch | git am --ignore-whitespace

The commit message is amended to match the conventions above and gets an Original pull request: #1000 reference so that GitHub links the commits to the pull request. Any further changes go into a separate Polishing. commit referencing the same issue, so that the contribution stays attributed to its author. Because of the cherry-pick based flow, a contributor’s GPG signature may be replaced by the maintainer’s signature when the commit is pushed to the target branches.

Releases

Releases are built and published by the GitHub Actions release workflows in .github/workflows. Pushing a release tag also triggers a full build of the documentation site, see Antora.