General Notes

• Set up your environment (one-time).

• Run help for a list of release tool commands.

• After fixing a failure, use workspace cleanup to reset state from the previous step.

Many steps use TLS. If a proxy or security tool adds trust anchors to the browser but not the JVM, Java may fail to connect; align trust with the JDK you use for the CLI, or turn off that interception while releasing.

The release process

The Pre-Release tasks and Post-Release tasks phases of making a release (opening and closing tickets) are locally ran tasks.

The Build and publish the release phase runs on the CI server.

flowchart LR
  pre[PreReleaseTasks] --> ci[BuildAndPublish]
  ci --> post[PostReleaseTasks]
  post --> more{MoreReleases}
  more -->|yes| pre
  more -->|no| postAll[PostAllReleasesTasks]

Loading

🍃 Pre-Release tasks

1. Ensure all work on CVEs potentially contained in the release is done (incl. backports etc.).

2. Upgrade dependencies in Spring Data Build parent pom (mind minor/major version rules).

3. Review open tickets for release:

   $ tracker open-tickets $trainIteration

4. Announce release preparations to the mailing list (https://groups.google.com/forum/#!forum/spring-data-dev).

5. Create the release tag, verify the release can be built, and publish tags:

   $ prepare-it $trainIteration

6. 🚥 Continue with Build and distribute the release.

🌿 Build and distribute the release

Action	Command
Go to the Spring Data Release repository
Start the Release Spring Data action	Run workflow on main branch and provide the $trainIteration

• For a Maven central release, if the smoke test has passed, the repository will already have been released, so there is nothing more to do.

• For an Artifactory release, if the smoke test has passed, the release will already have been staged and promoted, so there is nothing more to do.

• 🚥 Continue with Post-Release tasks.

🍀 Post-Release tasks

Action	Command
Close release tickets.	$ tracker close $trainIteration
Create new release versions and tickets for upcoming version	$ tracker setup-next $trainIteration.next

• 🚥 Go to Pre-Release tasks to ship the next release 🔂.

• 🚥 If this has been the last release 🏁, continue with Post-All-Releases tasks for the final steps.

🍃 Post-All-Releases tasks

Action	Command
Update versions in the Projects Service. $releaseTrains is given as comma separated lists of code names, without spaces. E.g. W,X,Y,Z	$ projects update $releaseTrains
Create list of docs for release announcements	$ announcement $trainIteration
Trigger Antora documentation build (once all artifacts have arrived at the final Maven repository)	$ release documentation $trainIteration
Announce release (Blog, Twitter) and notify downstream dependency projects as needed.	N.A.

Congratulations 🥳 You completed the release ❤️.

Appendix

One-Time Setup

Infrastructure requirements

• Ensure you have the credentials for buildmaster accounts on https://repo.spring.io.

Both are available in the Spring/Pivotal Last Pass repository.

Prepare local configuration and credentials

1. Add an application-local.properties file in the project root with the following properties:

   • git.username - Your GitHub username.

   • git.password - Your GitHub Password (or API key with scopes: public_repo, read:org, repo:status, repo_deployment, user when using 2FA).

   • git.author - Your full name (used for preparing commits).

   • git.email - Your email (used for preparing commits).

   • maven.mavenHome - Pointing to the location of your Maven installation.

   • deployment.username - Your Artifactory user.

   • deployment.api-key - The Artifactory API key to use for artifact promotion.

   • deployment.password - The encrypted Artifactory password.

   • gpg.keyname - The GPG key name.

   • gpg.passphrase - The password of your GPG key.

   • gpg.executable - Path to your GPG executable, typically /usr/local/MacGPG2/bin/gpg2 or /usr/local/bin/gpg.

   • project-service.key - Project Service authentication token. Must be a valid GitHub token. Can be the same as git.password when using a GitHub token as password. Use the following scopes: project, read:org, repo, user, workflow.

(See application-local.template for details.)

1. Verify your local settings (authentication, correct Maven, Java, and GPG setup):

   $ verify local

Detailed commands performed by spring-data-release-cli

The Post-Release tasks and Post-All-Releases tasks sections list the tracker, documentation, projects service, and announcement commands you run after CI; they are not repeated in the table below.

Action	Command
All release tickets are present	$ tracker releasetickets $trainIteration
Self-assign release tickets	$ tracker prepare $trainIteration
Prepare the release
	$ release prepare $trainIteration
	$ release conclude $trainIteration
Build the release
Build the artifacts from tag and push them to the appropriate maven repository. Also runs smoke tests, does Sonatype "release" if applicable, and does Artifactory "promote" if applicable.	$ release build $trainIteration
Distribute documentation and static resources from tag	$ release distribute $trainIteration
Push the created commits to GitHub	$ github push $trainIteration
Push new maintenance branches if the release version was a GA release (X.Y.0 version)	$ git push $trainIteration.next

Utilities

Java and Maven Versions used in the Container

Java and Maven versions are installed via SDKman during the Dockerfile build. See ci/java-tools.properties for further details.

GitHub Labels

ProjectLabelConfiguration contains a per-project configuration which labels should be present in a project. To apply that configuration (create or update), use:

$ github update labels $project [--commercial]

Dependency Upgrade

ProjectDependencies contains a per-project configuration of dependencies.

To check for dependency upgrades:

$ dependency check $trainIteration

This generates two files that report upgradable dependencies for Spring Data Build and Spring Data modules, respectively:

• dependency-upgrade-build.properties

  1. Edit this file to specify the dependencies and their corresponding version to upgrade. Removing a line will omit that dependency upgrade.

  2. Update dependency.upgrade.count value.

  3. Apply dependency upgrades to Spring Data Build:

     $ dependency upgrade $trainIteration

• dependency-upgrade-modules.properties

  1. Open a ticket for each dependency upgrade in the corresponding module (sample).

Dependency Report

Report store-specific dependencies to Spring Boot’s current upgrade ticket (sample).

To generate a dependency report:

$ dependency report $trainIteration

Maven Upgrade across Modules

To upgrade Maven across all modules:

1. Check for the latest stable Maven version.

   $ infra maven check $trainIteration

   • This generates a dependency-upgrade-maven.properties file that reports an upgradable version of Maven Wrapper, if it exists.

2. Apply Maven upgrade across all modules.

   $ infra maven upgrade $trainIteration

CI Properties Distribution

To distribute ci/pipeline.properties from Spring Data Build across all modules:

$ infra distribute ci-properties $trainIteration

GitHub Workflow Distribution

To distribute .github/workflows/project.yml from Spring Data Build across all modules:

$ infra distribute gh-workflow $trainIteration

Note that your GitHub token to authenticate against GitHub must have the workflow permission.

Broken Link Report

Resolve external links in reference documentation and print their status.

$ docs check-links $trainIteration

Flags for docs check-links:

Flag	Description
--local	read the documentation from disk (target module workspace directory)
--project	only check links of a specific project (eg. redis)
--report	only report errors of the given categories (ERROR,REDIRECT,OK). Default is ALL

Examples - Check links of release train/module

$ docs check-links Turing GA --report ERROR

$ docs check-links Turing SR1 --local true --project redis

Resolve external links of any web page (remote/local) and print their status.

$ check-links $url

Flags for check-links:

Flag	Description
--report	only report errors of the given categories (ERROR,REDIRECT,OK). Default is ALL

Example - Check links on any url

$ check-links file:///usr/git/spring-data-mongodb/target/site/reference/html/index.html --report ERROR,REDIRECT

Running the Tests

In order to run the test you need either MAVEN_HOME setup properly, or run your maven build like this:

mvn clean verify -Dmaven.maven-home=/opt/homebrew/bin/mvn

Obviously, the path given should be the location of your Maven installation.

Troubleshooting

Certificate Error (Local)

Happens typically when trying to resolve dependencies locally when running the preparation.

Solution: Check WSS and disable if running.

Conventions

$trainIteration

Release train label passed to CLI commands and CI (for example Turing GA or 2022.0.1).

$trainIteration.next

Literal placeholder usgithub trigger-downstream-workflow --source-repository spring-data-commons --workflow snapshots.yml --head-branch 3.5.xed in commands such as tracker setup-next and git push for the next train after the one you just shipped.

$releaseTrains

Comma-separated release-train code names with no spaces (for example X,Y,T).