spring-data-release

== General Notes

• Make sure to <<setup,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,Pre-Release tasks>> and <<post-release,Post-Release tasks>> phases of making a release (opening tickets/closing tickets) is still done manually.

The <<build,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]] === 🍃 Pre-Release tasks

. Ensure all work on CVEs potentially contained in the release is done (incl. backports etc.). . Upgrade dependencies in Spring Data Build parent pom (mind minor/major version rules). . Review open tickets for release:

$ tracker open-tickets $trainIteration

. Announce release preparations to mailing list (https://groups.google.com/forum/#!forum/spring-data-dev) . Create release tag, verify the release can be built, and publish tags:

$ prepare-it $trainIteration

. 🚥 Continue with <<build,Build and distribute the release>>.

[[build]] === 🌿 Build and distribute the release

[%header,cols="1,1"] |=== |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,Post-Release tasks>>.

[[post-release]] === 🍀 Post-Release tasks

[%header,cols="1,1"] |=== |Action |Command

|Close release tickets. |$ tracker close $trainIteration

|Create new release versions and tickets for upcoming version |$ tracker setup-next $trainIteration.next

|Update versions in the 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

|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

[[setup]] ==== 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.

(See link:application-local.template[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 2+| Prepare the release | |$ release prepare $trainIteration | |$ release conclude $trainIteration 2+| 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 2+| 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 https://sdkman.io/[SDKman] during the link:ci/Dockerfile[Dockerfile] build. See link:ci/java-tools.properties[ci/java-tools.properties] for further details.

===== GitHub Labels

link:src/main/java/org/springframework/data/release/issues/github/ProjectLabelConfiguration.java[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

link:src/main/java/org/springframework/data/release/infra/ProjectDependencies.java[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 (https://github.com/spring-projects/spring-data-redis/issues/2660[sample]).

===== Dependency Report

Report store-specific dependencies to Spring Boot's current upgrade ticket (https://github.com/spring-projects/spring-boot/issues/24036[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.

1. 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
[source,console]

$ 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
[source,console]

$ 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.