Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/spring-projects/spring-data-release

Command-line application to ship Spring Data releases
https://github.com/spring-projects/spring-data-release

Last synced: about 1 month ago
JSON representation

Command-line application to ship Spring Data releases

Awesome Lists containing this project

README 

        
== General Notes



* Make sure to <>.

* 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 <> and <> phases of making a release (opening tickets/closing tickets) is still done manually.



The <> phase is what's covered by the CI server.



Note many steps of the release process use SSL connections. If you are "using" a tool that performs a MITM attack on SSL connections by adding extra root certificates in your browsers but not in the Java keychain, the process will fail with some error indicating the inability to establish a secure conection.



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



[%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



[%header,cols="1,1"]

|===

|Action

|Command



|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

----



===== GitHub Workflow Distribution



To distribute `.github/workflows/project.yml` from Spring Data Build across all modules:



----

$ infra distribute gh-workflow $trainIteration

----



Note that your GitHub token to authenticate against GitHub must have the `workflow` permission.



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