288 lines
9.7 KiB
Plaintext
288 lines
9.7 KiB
Plaintext
== 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:
|
|
|
|
$ 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
|
|
|
|
| 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. `$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.
|
|
1. Update `dependency.upgrade.count` value.
|
|
1. 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
|
|
----
|
|
|
|
|
|
===== 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. |