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

[[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 (CLI: `$ 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 (CLI: `$ prepare-it $trainIteration`)
. 🚥 Continue with `Build and distribute the release`

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

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

|Check out this repository from GitHub
|`$ git clone git@github.com:spring-projects/spring-data-release.git`

|Checkout the `main` branch
|`$ git checkout main`

|Edit `ci/release.properties` and assign the version number of the release train you wish to release to `release.version`. (Make sure it's NOT commented out!)
|

|Commit the change to this repository
|`$ git add ci/release.properties && git commit`

|Switch to the `release` branch
|`$ git checkout release`

|Set the `HEAD` to `main` to point the content to what is on `main`
|`$ git reset --hard main`

|🚨 *To trigger 🛣 the release* `git push` the `release` branch
|`$ git push origin release`

|Go to https://jenkins.spring.io/view/SpringData/job/spring-data-release/job/release, Navigate to the `release` branch.
A job should have 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]]
=== 🍀 Post-Release tasks

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

| Finally, push the commit that changed `release.properties` to `main`
| `$ git push origin main` (where you've checked out `spring-data-release`)

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

|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

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.

After that, run the `verify-local` command (`$ verify-local`) to verify your local settings (authentication, correct Maven, Java, and GPG setup).

See `application-local.template` for details.

==== 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`
|Update versions in Projects Service. `$targets` 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

`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
----

===== Dependency Upgrade

`ProjectDependencies` contains a per-project configuration of dependencies.

Workflow:

* Check for dependency upgrades `$ dependency check $trainIteration`

Reports upgradable dependencies for Build and Modules and
creates `dependency-upgrade-build.properties` file.
Edit `dependency-upgrade-build.properties` to specify the dependency version to upgrade.
Removing a line will omit that dependency upgrade.

* Apply dependency upgrade with `$ dependency upgrade $trainIteration`. Applies dependency
 upgrades currently only to Spring Data Build.
* Report store-specific dependencies to Spring Boot's current upgrade
 ticket (https://github.com/spring-projects/spring-boot/issues/24036[sample]) `$ dependency report $trainIteration`

===== CI Properties Distribution

To distribute `ci/pipeline.properties` across all modules use:

`$ infra distribute ci-properties $trainIteration`

===== 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
----