diff --git a/readme.adoc b/readme.adoc new file mode 100644 index 0000000..5898825 --- /dev/null +++ b/readme.adoc @@ -0,0 +1,161 @@ +== 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 yoiu 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 ` +* `release build ` +* `release conclude ` +* `github push ` +* `release distribute ` + +...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 ` +. 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 ` +. `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` diff --git a/readme.md b/readme.md deleted file mode 100644 index de4fe2f..0000000 --- a/readme.md +++ /dev/null @@ -1,99 +0,0 @@ -## 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 - - -| 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* | -| **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. | -| **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`| -| **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 ([sample](https://github.com/spring-projects/spring-boot/issues/24036)) `$ dependency report $trainIteration` - -#### CI Properties Distribution - -To distribute `ci/pipeline.properties` across all modules use: - -`$ infra distribute ci-properties $trainIteration`