General Notes

• Make sure to initially set-up your environment.

• Use the command help to get a list of all commands in the release tools.

• After fixing a problem use workspace cleanup to clean-up any mess left behind by the previous step.

The release process

The Pre-Release tasks and Post-Release tasks phases of making a release (opening tickets/closing tickets) is still done manually.

The Build and publish the release phase is what’s covered by the CI server.

Note many steps of the release process use SSL connections. If you are "using" a tool that performs a MITM attack on SSL connections by adding extra root certificates in your browsers but not in the Java keychain, the process will fail with some error indicating the inability to establish a secure conection.

🍃 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 mailing list (https://groups.google.com/forum/#!forum/spring-data-dev)

5. Create 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
Open a terminal pointing to the release tools directory
Checkout the release branch	$ git checkout release
Set the HEAD to main to point the content to what is on main	$ git reset --hard main
Edit ci/release.properties and assign the version number of the release train you wish to release to release.version.
Commit the change to this repository	$ git add ci/release.properties && git commit
git push the release branch	$ git push -f origin release
🚨 To trigger 🛣 the release manually on Jenkins. Goto https://jenkins.spring.io/view/SpringData/job/spring-data-release/job/release/ and click ▶ Build Now
Once started click on the active job, and then click on Open Blue Ocean.	Monitor the release process.

• 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 to the project root and add 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

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
Post-release tasks
Close JIRA tickets and GitHub release tickets.	$ tracker close $trainIteration
Create new release versions and tickets for upcoming version	$ tracker setup-next $trainIteration.next
Trigger Antora documentation build (once all artifacts have arrived at the final Maven repository)	$ release documentation $trainIteration
Update versions in Projects Service. $releaseTrains is given as comma separated lists of code names, without spaces. E.g. Moore,Neumann	$ projects update $releaseTrains
Create list of docs for release announcements	$ announcement $trainIteration

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

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

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 when tyring to resolve dependencies locally when running the preparation.

Solution: Check WSS and disable if running.

Docker Image Unavailable (CI)

Happens typically after bumping the java version which does not necessarily trigger container recreation.

10:41:58  Error: No such object: springci/spring-data-release-tools:0.27

Solution: alter the Dockerfile (eg. add a newline) and push things again. This will trigger the rebuild of the release tools container image.