== 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). . All release tickets are present (CLI: `$ tracker releasetickets $trainIteration`) . Review open tickets for release. . Self-assign release tickets (CLI: `$ tracker prepare $trainIteration`) . Announce release preparations to mailing list (https://groups.google.com/forum/#!forum/spring-data-dev) . 🚥 Continue with `Build and publish the release` [[build]] === 🌿 Build and publish 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-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. |=== After preparing and building (approx. 20 minutes), the Jenkins pipeline will pause, indicating it's time to smoke test the staged release, and put up a prompt: *Proceed* or *Abort*. 🚨 If you click on *Proceed*, then it will continue on to the `release conclude`/`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. * 🚥 Continue with `Post-release tasks` *Background* ==== The first CI phase includes: `release prepare` and `release build` and may take twenty minutes or so. * 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". 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. + 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. ==== [[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 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. |=== 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. * 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. ==== 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+| *Release the binaries* | |`$ release prepare $trainIteration` |Build the artefacts and push them to the appropriate maven repository |`$ release build $trainIteration` | |`$ release conclude $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` |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` |=== ==== 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`