== General Notes * Use the command `help` to get a list of all commands in the release tools. * After fixing a problem use `workspace cleanup` to cleanup any mess left behind by the previous step. == One Time Setup === Infrastructure requirements * Ensure you have the credentials for `buildmaster` accounts on https://repo.spring.io. * Ensure you have the credentials for https://oss.sonatype.org (to deploy and promote GA and service releases, need deployment permissions for `org.springframework.data`) in `settings.xml` for server with id `sonatype`. 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`. * `sagan.key` - Sagan 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` command (`$ verify`) to verify your settings (authentication, correct Maven, Java, and GPG setup). See `application-local.template` for details. == The release process The *Pre-release checks* and *Post-release tasks* phases of making a release (opening tickets/closing tickets) is still done manually. The *Release the binaries* phase is what's covered by the CI server. This includes the following actions: * `workspace cleanup` * `release prepare <VERSION>` * `release build <VERSION>` * `release conclude <VERSION>` * `github push <VERSION>` * `release distribute <VERSION>` ...are now done by the CI server as shown below. To make a release: . Check out this repository from github. . Create a branch off of `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 (but don't push to github). . Tag the commit. . Checkout/create a `release` branch and do a `git reset --hard <tag>` . Force push it to github with `git push -f origin release` . Go to https://jenkins.spring.io/view/SpringData/job/spring-data-release-release/ . Navigate to the `release` branch. . A job should have started. If not, you may have to manually launch it. . Click on the active job, and then click on *Open Blue Ocean*. . Monitor the release process. The first CI phase includes: `release prepare` and `release build` and may take twenty minutes or so. After that, the Jenkins pipeline will pause, indicating it's time to smoke test the staged release, and put up a prompt: *Proceed* or *Abort*. For a maven central release, you can visit https://s01.oss.sonatype.org/, login, and inspect the staged Spring Data Release. All the Spring Data modules will inside one repository. For a milestone/RC release, you can visit https://repo.spring.io/. All the Spring Data modules will be there, each module a separate "build". NOTE: At this point in time, we don't have official Spring Data Release smoke testing configured, so you can simply click *Proceed* if there were no issues. NOTE: For milestone/RC releases, Spring Data Release tools automatically promotes them in Artifactory, so if you have to delete a build, you'll ALSO have to go and delete each module individually. If you click on *Proceed*, then it will continue on to the `release conclude` phase. After that, it will pause, indicating everything is ready to complete, and put up a prompt: *Proceed* or *Abort*. If you click on *Proceed*, then it will continue on to the `github push`/`release distribute` phase. * For a maven central release, go to https://s01.oss.sonatype.org/ and login. ** After logging in, you will find a closed Spring Data Release repository. ** Click the repository and then choose "Release". * For an artifactory release, the release will already have been staged and promoted, so there is nothing more to do. Congratulations! You completed the release. For some final bookkeeping, merge the branch you created at the beginning of the process to `main`: . `git checkout main` . `git merge <yourbranch>` . `git push` . `git push --tags` === Detailed commands performed by `spring-data-release-cli` |=== |Action |Command |Build and execute the release shell |`mvn package && java -jar target/spring-data-release-cli.jar` | |_All following commands are run in the release shell_ 2+|*Pre-release checks* |Ensure all work on CVEs potentially contained in the release is done (incl. backports etc.) |N.A. |Upgrade dependencies in Spring Data Build parent pom (mind minor/major version rules) |N.A. |All release tickets are present |`$ tracker releasetickets $trainIteration` |Review open tickets for release |N.A. |Self-assign release tickets |`$ tracker prepare $trainIteration` |Announce release preparations to mailing list (https://groups.google.com/forum/#!forum/spring-data-dev) |N.A. 2+| *Release the binaries* | |`$ release prepare $trainIteration` |Build the artefacts and push them to the apropriate maven repository |`$ release build $trainIteration` | |`$ release conclude $trainIteration` |Push the created commits to GitHub |`$ github push $trainIteration` |Push new maintanance branches if the release version was a GA release (`X.Y.0` version) |`$ git push $trainIteration.next` |Distribute documentation and static resources from tag |`$ release distribute $trainIteration` 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 Sagan. `$targets` is given as comma separated lists of code names, without spaces. E.g. `Moore,Neumann` |`$ sagan update $releasetrains` |Create list of docs for release announcements |`$ announcement $trainIteration` |Announce release (Blog, Twitter) and notify downstream dependency projects as needed. |N.A. |=== === Utilities ==== 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`