SpringCloud/spring-cloud-release-tools
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

updated the docs

Browse Source
This commit is contained in:
Marcin Grzejszczak
2021-02-08 17:49:11 +01:00
parent 120082eadc
commit f70567aa05
3 changed files with 300 additions and 293 deletions
Download Patch File Download Diff File Expand all files Collapse all files

299
README.adoc
View File

@@ -17,6 +17,149 @@ image::https://codecov.io/gh/{org}/{repo}/branch/{branch}/graph/badge.svg["codec
Spring Cloud projects reuse the same pattern of building and deploying the applications.
That's why this tool makes it easy to automate the release / dependency update process of our applications.
=== Releasing through Jenkins
NOTE: Whenever a release process is broken, Jenkins marks it with a red ball and breaks the build.
Whenever a post-release action went wrong but the release is successful, Jenkins marks the build with a yellow ball and marks the build as unstable.
==== Releasing a Single Project
Let us assume that we are to release `spring-cloud-build` project.
We need to do the following steps:
. Create a branch (for example, `springCloudBuildRelease`) in a project that contains a BOM (for example, https://github.com/spring-cloud/spring-cloud-release/[spring-cloud-release]).
The following example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout -b springCloudBuildRelease
```
. Update *all* versions as if you were doing a release train.
We need to update the project's versions, Boot version, and dependencies versions, too.
Let us assume that we will eventually be doing a release train for the `Hoxton.M1` release, Spring Boot to the latest available one, and `spring-cloud-commons` to `1.2.3.BUILD-SNAPSHOT`.
The following example shows how to do so:
```bash
// setting the release train value
$ ./mvnw versions:set -DnewVersion=Hoxton.M1 -DgenerateBackupPoms=false -DprocessAllModules=true
// Update all parent versions
$ ./mvnw versions:update-parent -DgenerateBackupPoms=false -DprocessAllModules=true
// Setting the necessary dependencies
$ ./mvnw versions:set-property -Dproperty=spring-cloud-commons.version -DnewVersion=1.2.3.BUILD-SNAPSHOT -pl spring-cloud-dependencies -DgenerateBackupPoms=false
// NOTE!!!
// Verify that the versions set by Maven are correct!!
$ git diff
// commit and push the branch
$ git add . && git commit -m "Updating project for Spring Cloud Build release" && git push origin springCloudBuildRelease
```
IMPORTANT: If you're doing a e.g. `M1` release, remember to not have any snapshot versions in this branch.
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], which the following image shows:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/releasers.png[Releaser view]
. Pick the proper releaser project (for example, `spring-cloud-build-releaser`).
The following image shows the settings for this example:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/scBuildReleaser.png[Spring Cloud Build Releaser - build with parameters]
. Next, click `Build with parameters`.
The following image shows the UI for doing so:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/runningScBuildReleaser.png[Updated `RELEASER_POM_BRANCH`]
Pick from which branch you would like the project (for example, `spring-cloud-build` - defaults to `master`) to be built and update the `RELEASER_POM_BRANCH` to point to the checked-out branch of Spring Cloud Release (for example, `springCloudBuildRelease`).
You can pick whether you want to perform only post-release tasks or the whole release.
. Finally, click `Build`.
You are done!
As a post action, do not forget to remove the branch.
The following example shows how to do so:
```bash
// to synchronize any deleted branches (don't run this if you want leave any deleted branches that were deleted in the origin)
$ git fetch -p
$ git branch -d springCloudBuildRelease
$ git push origin --delete springCloudBuildRelease
```
==== Releasing a Release Train
We call a release train a `meta-release`.
In order to perform one, you need to:
. In your project (which must contain a BOM, such as `spring-cloud-release`) you have to have a branch, where you store properties with versions of your projects.
For example, the branch name can be https://github.com/spring-cloud/spring-cloud-release/tree/jenkins-releaser-config[jenkins-releaser-config]).
The following example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout jenkins-releaser-config
```
. Create a file that contains all properties for a given release train.
The name of the release train should be lowercase, and dots should be converted to underscores.
For example, for the `Greenwich.SR2` release train we need to have a file named `greenwich_sr2.properties`.
The following example shows how to do so:
```bash
$ touch greenwich_sr2.properties
```
. We need to update the file with all versions for the release train.
The properties file contains an *ordered* list of `releaser.fixed-versions[project-name]=project-version` entries, as the following listing shows:
```bash
$ echo "releaser.fixed-versions[spring-boot]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-build]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-commons]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-function]=2.0.2.RELEASE
releaser.fixed-versions[spring-cloud-stream]=Fishtown.SR3
releaser.fixed-versions[spring-cloud-aws]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-bus]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-task]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-config]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-netflix]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-cloudfoundry]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-kubernetes]=1.0.2.RELEASE
releaser.fixed-versions[spring-cloud-openfeign]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-consul]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gateway]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-security]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-sleuth]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-zookeeper]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-contract]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gcp]=1.1.2.RELEASE
releaser.fixed-versions[spring-cloud-vault]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-release]=Greenwich.SR2" >> greenwich_sr2.properties
$ git add greenwich_sr2.properties && git commit -m "Added Greenwich.SR2 properties" && git push origin jenkins-releaser-config
```
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], as the following image shows:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/releasersForMetaRelease.png[Releaser view]
. Pick the proper meta-releaser project (for example, `spring-cloud-meta-releaser`), as the following image shows:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/springCloudMetaRelease.png[Spring Cloud Meta Releaser - build with parameters]
. Next, click `Build with parameters`.
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/runningSpringCloudMetaReleaser.png[Spring Cloud Meta Releaser view]
You have quite a few options to pick, but the most important one is to set the value of the `RELEASE_VERSION` to the given release train version (for example, `Greenwich.SR2`).
Continue updating the rest of the fields if necessary and read the field descriptions and this documentation for more information.
. Finally, click `Build`.
You are done!
=== What does it do?
==== Single project
@@ -403,7 +546,7 @@ Below you can find a table with all the releaser options.
|releaser.bash.deploy-command | echo "{{systemProps}}" | Command to be executed to deploy a built project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.deploy-guides-command | echo "{{systemProps}}" | Command to be executed to build and deploy guides project only. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.generate-release-train-docs-command | echo "{{version}}" | Command to be executed to generate release train documentation.
|releaser.bash.publish-docs-commands | [mkdir -p target, echo "{{version}}"] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.publish-docs-command | [mkdir -p target, echo "{{version}}"] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.system-properties | | Additional system properties that should be passed to the build / deploy commands. If present in other commands "{{systemProps}}" will be substituted with this property.
|releaser.bash.wait-time-in-minutes | 20 | Max wait time in minutes for the process to finish.
|releaser.fixed-versions | | Project name to its version - overrides all versions retrieved from a release train repository like Spring Cloud Release.
@@ -441,14 +584,14 @@ Below you can find a table with all the releaser options.
|releaser.gradle.generate-release-train-docs-command | ./gradlew generateReleaseTrainDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}} | Command to be executed to generate release train documentation.
|releaser.gradle.gradle-props-substitution | | A mapping that should be applied to {@code gradle.properties} in order to perform a substitution of properties. The mapping is from a property inside {@code gradle.properties} to the projects name. Example. In {@code gradle.properties} you have {@code verifierVersion=1.0.0} . You want this property to get updated with the value of {@code spring-cloud-contract} version. Then it's enough to do the mapping like this for this Releaser's property: {@code verifierVersion=spring-cloud-contract}.
|releaser.gradle.ignored-gradle-regex | | List of regular expressions of ignored gradle props. Defaults to test projects and samples.
|releaser.gradle.publish-docs-commands | [./gradlew publishDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.gradle.publish-docs-command | [./gradlew publishDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.gradle.system-properties | | Additional system properties that should be passed to the build / deploy commands. If present in other commands "{{systemProps}}" will be substituted with this property.
|releaser.gradle.wait-time-in-minutes | 20 | Max wait time in minutes for the process to finish.
|releaser.maven.build-command | ./mvnw clean install -B -Pdocs {{systemProps}} | Command to be executed to build the project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.maven.deploy-command | ./mvnw deploy -DskipTests -B -Pfast,deploy {{systemProps}} | Command to be executed to deploy a built project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.maven.deploy-guides-command | ./mvnw clean verify deploy -B -Pguides,integration -pl guides {{systemProps}} | Command to be executed to build and deploy guides project only. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.maven.generate-release-train-docs-command | bash release_train.sh --retrieveversions --version {{version}} --ghpages --auto | Command to be executed to generate release train documentation.
|releaser.maven.publish-docs-commands | [mkdir -p target, wget https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/ghpages.sh -O target/gh-pages.sh, chmod +x target/gh-pages.sh, ./target/gh-pages.sh -v {{version}} -c] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.maven.publish-docs-command | [mkdir -p target, wget https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/ghpages.sh -O target/gh-pages.sh, chmod +x target/gh-pages.sh, ./target/gh-pages.sh -v {{version}} -c] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.maven.system-properties | | Additional system properties that should be passed to the build / deploy commands. If present in other commands "{{systemProps}}" will be substituted with this property.
|releaser.maven.wait-time-in-minutes | 20 | Max wait time in minutes for the process to finish.
|releaser.meta-release.enabled | false | Are we releasing the whole suite of apps or only one?
@@ -530,149 +673,6 @@ $ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/
$ java -jar target/releaser-spring-1.0.0.M1.jar --releaser.working-dir=/path/to/project/root
----
=== Releasing through Jenkins
NOTE: Whenever a release process is broken, Jenkins marks it with a red ball and breaks the build.
Whenever a post-release action went wrong but the release is successful, Jenkins marks the build with a yellow ball and marks the build as unstable.
==== Releasing a Single Project
Let us assume that we are to release `spring-cloud-build` project.
We need to do the following steps:
. Create a branch (for example, `springCloudBuildRelease`) in a project that contains a BOM (for example, https://github.com/spring-cloud/spring-cloud-release/[spring-cloud-release]).
The following example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout -b springCloudBuildRelease
```
. Update *all* versions as if you were doing a release train.
We need to update the project's versions, Boot version, and dependencies versions, too.
Let us assume that we will eventually be doing a release train for the `Hoxton.M1` release, Spring Boot to the latest available one, and `spring-cloud-commons` to `1.2.3.BUILD-SNAPSHOT`.
The following example shows how to do so:
```bash
// setting the release train value
$ ./mvnw versions:set -DnewVersion=Hoxton.M1 -DgenerateBackupPoms=false -DprocessAllModules=true
// Update all parent versions
$ ./mvnw versions:update-parent -DgenerateBackupPoms=false -DprocessAllModules=true
// Setting the necessary dependencies
$ ./mvnw versions:set-property -Dproperty=spring-cloud-commons.version -DnewVersion=1.2.3.BUILD-SNAPSHOT -pl spring-cloud-dependencies -DgenerateBackupPoms=false
// NOTE!!!
// Verify that the versions set by Maven are correct!!
$ git diff
// commit and push the branch
$ git add . && git commit -m "Updating project for Spring Cloud Build release" && git push origin springCloudBuildRelease
```
IMPORTANT: If you're doing a e.g. `M1` release, remember to not have any snapshot versions in this branch.
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], which the following image shows:
image::{github-raw}/docs/src/main/asciidoc/images/releasers.png[Releaser view]
. Pick the proper releaser project (for example, `spring-cloud-build-releaser`).
The following image shows the settings for this example:
image::{github-raw}/docs/src/main/asciidoc/images/scBuildReleaser.png[Spring Cloud Build Releaser - build with parameters]
. Next, click `Build with parameters`.
The following image shows the UI for doing so:
image::{github-raw}/docs/src/main/asciidoc/images/runningScBuildReleaser.png[Updated `RELEASER_POM_BRANCH`]
Pick from which branch you would like the project (for example, `spring-cloud-build` - defaults to `master`) to be built and update the `RELEASER_POM_BRANCH` to point to the checked-out branch of Spring Cloud Release (for example, `springCloudBuildRelease`).
You can pick whether you want to perform only post-release tasks or the whole release.
. Finally, click `Build`.
You are done!
As a post action, do not forget to remove the branch.
The following example shows how to do so:
```bash
// to synchronize any deleted branches (don't run this if you want leave any deleted branches that were deleted in the origin)
$ git fetch -p
$ git branch -d springCloudBuildRelease
$ git push origin --delete springCloudBuildRelease
```
==== Releasing a Release Train
We call a release train a `meta-release`.
In order to perform one, you need to:
. In your project (which must contain a BOM, such as `spring-cloud-release`) you have to have a branch, where you store properties with versions of your projects.
For example, the branch name can be https://github.com/spring-cloud/spring-cloud-release/tree/jenkins-releaser-config[jenkins-releaser-config]).
The folloiwng example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout jenkins-releaser-config
```
. Create a file that contains all properties for a given release train.
The name of the release train should be lowercase, and dots should be converted to underscores.
For example, for the `Greenwich.SR2` release train we need to have a file named `greenwich_sr2.properties`.
The following example shows how to do so:
```bash
$ touch greenwich_sr2.properties
```
. We need to update the file with all versions for the release train.
The properties file contains an *ordered* list of `releaser.fixed-versions[project-name]=project-version` entries, as the following listing shows:
```bash
$ echo "releaser.fixed-versions[spring-boot]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-build]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-commons]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-function]=2.0.2.RELEASE
releaser.fixed-versions[spring-cloud-stream]=Fishtown.SR3
releaser.fixed-versions[spring-cloud-aws]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-bus]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-task]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-config]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-netflix]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-cloudfoundry]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-kubernetes]=1.0.2.RELEASE
releaser.fixed-versions[spring-cloud-openfeign]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-consul]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gateway]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-security]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-sleuth]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-zookeeper]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-contract]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gcp]=1.1.2.RELEASE
releaser.fixed-versions[spring-cloud-vault]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-release]=Greenwich.SR2" >> greenwich_sr2.properties
$ git add greenwich_sr2.properties && git commit -m "Added Greenwich.SR2 properties" && git push origin jenkins-releaser-config
```
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], as the following image shows:
image::{github-raw}/docs/src/main/asciidoc/images/releasersForMetaRelease.png[Releaser view]
. Pick the proper meta-releaser project (for example, `spring-cloud-meta-releaser`), as the following image shows:
image::{github-raw}/docs/src/main/asciidoc/images/springCloudMetaRelease.png[Spring Cloud Meta Releaser - build with parameters]
. Next, click `Build with parameters`.
image::{github-raw}/docs/src/main/asciidoc/images/runningSpringCloudMetaReleaser.png[Spring Cloud Meta Releaser view]
You have quite a few options to pick, but the most important one is to set the value of the `RELEASE_VERSION` to the given release train version (for example, `Greenwich.SR2`).
Continue updating the rest of the fields if necessary and read the field descriptions and this documentation for more information.
. Finally, click `Build`.
You are done!
=== FAQ
==== JSchException: Auth fail
@@ -708,7 +708,7 @@ $ ssh-add ~/.ssh/id_rsa
== Building
:jdkversion: 1.7
:jdkversion: 1.8
=== Basic Compile and Test
@@ -770,6 +770,11 @@ https://eclipse.org[Eclipse] when working with the code. We use the
https://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools
should also work without issue as long as they use Maven 3.3.3 or better.
==== Activate the Spring Maven profile
Spring Cloud projects require the 'spring' Maven profile to be activated to resolve
the spring milestone and snapshot repositories. Use your preferred IDE to set this
profile to be active, or you may experience build errors.
==== Importing into eclipse with m2eclipse
We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with
eclipse. If you don't already have m2eclipse installed it is available from the "eclipse

8
docs/src/main/asciidoc/_configprops.adoc
View File

@@ -5,7 +5,7 @@
|releaser.bash.deploy-command | echo "{{systemProps}}" | Command to be executed to deploy a built project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.deploy-guides-command | echo "{{systemProps}}" | Command to be executed to build and deploy guides project only. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.generate-release-train-docs-command | echo "{{version}}" | Command to be executed to generate release train documentation.
|releaser.bash.publish-docs-command | [mkdir -p target, echo "{{version}}"] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.publish-docs-command | mkdir -p target && echo "{{version}}" | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.bash.system-properties | | Additional system properties that should be passed to the build / deploy commands. If present in other commands "{{systemProps}}" will be substituted with this property.
|releaser.bash.wait-time-in-minutes | 20 | Max wait time in minutes for the process to finish.
|releaser.fixed-versions | | Project name to its version - overrides all versions retrieved from a release train repository like Spring Cloud Release.
@@ -17,8 +17,10 @@
|releaser.git.fetch-versions-from-git | true | If {@code true} then should fill the map of versions from Git. If {@code false} then picks fixed versions.
|releaser.git.number-of-checked-milestones | 50 | In order not to iterate endlessly over milestones we introduce a threshold of milestones that we will go through to find the matching milestone.
|releaser.git.oauth-token | | GitHub OAuth token to be used to interact with GitHub repo.
|releaser.git.org-name | | The organization name on Github.
|releaser.git.password | | Optional Git password. If not passed keys will be used for authentication.
|releaser.git.release-train-bom-url | | URL to a release train repository.
|releaser.git.release-train-branch | | Branch to check out for the release train.
|releaser.git.release-train-docs-branch | | Branch to check out for the release train docs.
|releaser.git.release-train-docs-url | | URL to the release train documentation.
|releaser.git.release-train-wiki-page-prefix | | Page prefix for the release train wiki. E.g. for [Spring-Cloud-Finchley-Release-Notes] it would be [Spring-Cloud].
@@ -43,14 +45,14 @@
|releaser.gradle.generate-release-train-docs-command | ./gradlew generateReleaseTrainDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}} | Command to be executed to generate release train documentation.
|releaser.gradle.gradle-props-substitution | | A mapping that should be applied to {@code gradle.properties} in order to perform a substitution of properties. The mapping is from a property inside {@code gradle.properties} to the projects name. Example. In {@code gradle.properties} you have {@code verifierVersion=1.0.0} . You want this property to get updated with the value of {@code spring-cloud-contract} version. Then it's enough to do the mapping like this for this Releaser's property: {@code verifierVersion=spring-cloud-contract}.
|releaser.gradle.ignored-gradle-regex | | List of regular expressions of ignored gradle props. Defaults to test projects and samples.
|releaser.gradle.publish-docs-command | [./gradlew publishDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.gradle.publish-docs-command | ./gradlew publishDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}} | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.gradle.system-properties | | Additional system properties that should be passed to the build / deploy commands. If present in other commands "{{systemProps}}" will be substituted with this property.
|releaser.gradle.wait-time-in-minutes | 20 | Max wait time in minutes for the process to finish.
|releaser.maven.build-command | ./mvnw clean install -B -Pdocs {{systemProps}} | Command to be executed to build the project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.maven.deploy-command | ./mvnw deploy -DskipTests -B -Pfast,deploy {{systemProps}} | Command to be executed to deploy a built project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.maven.deploy-guides-command | ./mvnw clean verify deploy -B -Pguides,integration -pl guides {{systemProps}} | Command to be executed to build and deploy guides project only. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating.
|releaser.maven.generate-release-train-docs-command | bash release_train.sh --retrieveversions --version {{version}} --ghpages --auto | Command to be executed to generate release train documentation.
|releaser.maven.publish-docs-command | [mkdir -p target, wget https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/docs/src/main/asciidoc/ghpages.sh -O target/gh-pages.sh, chmod +x target/gh-pages.sh, ./target/gh-pages.sh -v {{version}} -c] | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.maven.publish-docs-command | ./mvnw deploy -DskipTests -B -Pfast,deploy,docs -pl docs {{systemProps}} | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version.
|releaser.maven.system-properties | | Additional system properties that should be passed to the build / deploy commands. If present in other commands "{{systemProps}}" will be substituted with this property.
|releaser.maven.wait-time-in-minutes | 20 | Max wait time in minutes for the process to finish.
|releaser.meta-release.enabled | false | Are we releasing the whole suite of apps or only one?

286
docs/src/main/asciidoc/spring-cloud-release-tools.adoc
View File

@@ -3,6 +3,149 @@
Spring Cloud projects reuse the same pattern of building and deploying the applications.
That's why this tool makes it easy to automate the release / dependency update process of our applications.
=== Releasing through Jenkins
NOTE: Whenever a release process is broken, Jenkins marks it with a red ball and breaks the build.
Whenever a post-release action went wrong but the release is successful, Jenkins marks the build with a yellow ball and marks the build as unstable.
==== Releasing a Single Project
Let us assume that we are to release `spring-cloud-build` project.
We need to do the following steps:
. Create a branch (for example, `springCloudBuildRelease`) in a project that contains a BOM (for example, https://github.com/spring-cloud/spring-cloud-release/[spring-cloud-release]).
The following example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout -b springCloudBuildRelease
```
. Update *all* versions as if you were doing a release train.
We need to update the project's versions, Boot version, and dependencies versions, too.
Let us assume that we will eventually be doing a release train for the `Hoxton.M1` release, Spring Boot to the latest available one, and `spring-cloud-commons` to `1.2.3.BUILD-SNAPSHOT`.
The following example shows how to do so:
```bash
// setting the release train value
$ ./mvnw versions:set -DnewVersion=Hoxton.M1 -DgenerateBackupPoms=false -DprocessAllModules=true
// Update all parent versions
$ ./mvnw versions:update-parent -DgenerateBackupPoms=false -DprocessAllModules=true
// Setting the necessary dependencies
$ ./mvnw versions:set-property -Dproperty=spring-cloud-commons.version -DnewVersion=1.2.3.BUILD-SNAPSHOT -pl spring-cloud-dependencies -DgenerateBackupPoms=false
// NOTE!!!
// Verify that the versions set by Maven are correct!!
$ git diff
// commit and push the branch
$ git add . && git commit -m "Updating project for Spring Cloud Build release" && git push origin springCloudBuildRelease
```
IMPORTANT: If you're doing a e.g. `M1` release, remember to not have any snapshot versions in this branch.
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], which the following image shows:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/releasers.png[Releaser view]
. Pick the proper releaser project (for example, `spring-cloud-build-releaser`).
The following image shows the settings for this example:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/scBuildReleaser.png[Spring Cloud Build Releaser - build with parameters]
. Next, click `Build with parameters`.
The following image shows the UI for doing so:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/runningScBuildReleaser.png[Updated `RELEASER_POM_BRANCH`]
Pick from which branch you would like the project (for example, `spring-cloud-build` - defaults to `master`) to be built and update the `RELEASER_POM_BRANCH` to point to the checked-out branch of Spring Cloud Release (for example, `springCloudBuildRelease`).
You can pick whether you want to perform only post-release tasks or the whole release.
. Finally, click `Build`.
You are done!
As a post action, do not forget to remove the branch.
The following example shows how to do so:
```bash
// to synchronize any deleted branches (don't run this if you want leave any deleted branches that were deleted in the origin)
$ git fetch -p
$ git branch -d springCloudBuildRelease
$ git push origin --delete springCloudBuildRelease
```
==== Releasing a Release Train
We call a release train a `meta-release`.
In order to perform one, you need to:
. In your project (which must contain a BOM, such as `spring-cloud-release`) you have to have a branch, where you store properties with versions of your projects.
For example, the branch name can be https://github.com/spring-cloud/spring-cloud-release/tree/jenkins-releaser-config[jenkins-releaser-config]).
The following example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout jenkins-releaser-config
```
. Create a file that contains all properties for a given release train.
The name of the release train should be lowercase, and dots should be converted to underscores.
For example, for the `Greenwich.SR2` release train we need to have a file named `greenwich_sr2.properties`.
The following example shows how to do so:
```bash
$ touch greenwich_sr2.properties
```
. We need to update the file with all versions for the release train.
The properties file contains an *ordered* list of `releaser.fixed-versions[project-name]=project-version` entries, as the following listing shows:
```bash
$ echo "releaser.fixed-versions[spring-boot]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-build]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-commons]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-function]=2.0.2.RELEASE
releaser.fixed-versions[spring-cloud-stream]=Fishtown.SR3
releaser.fixed-versions[spring-cloud-aws]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-bus]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-task]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-config]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-netflix]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-cloudfoundry]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-kubernetes]=1.0.2.RELEASE
releaser.fixed-versions[spring-cloud-openfeign]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-consul]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gateway]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-security]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-sleuth]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-zookeeper]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-contract]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gcp]=1.1.2.RELEASE
releaser.fixed-versions[spring-cloud-vault]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-release]=Greenwich.SR2" >> greenwich_sr2.properties
$ git add greenwich_sr2.properties && git commit -m "Added Greenwich.SR2 properties" && git push origin jenkins-releaser-config
```
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], as the following image shows:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/releasersForMetaRelease.png[Releaser view]
. Pick the proper meta-releaser project (for example, `spring-cloud-meta-releaser`), as the following image shows:
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/springCloudMetaRelease.png[Spring Cloud Meta Releaser - build with parameters]
. Next, click `Build with parameters`.
image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/master/docs/src/main/asciidoc/images/runningSpringCloudMetaReleaser.png[Spring Cloud Meta Releaser view]
You have quite a few options to pick, but the most important one is to set the value of the `RELEASE_VERSION` to the given release train version (for example, `Greenwich.SR2`).
Continue updating the rest of the fields if necessary and read the field descriptions and this documentation for more information.
. Finally, click `Build`.
You are done!
=== What does it do?
==== Single project
@@ -435,149 +578,6 @@ $ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/
$ java -jar target/releaser-spring-1.0.0.M1.jar --releaser.working-dir=/path/to/project/root
----
=== Releasing through Jenkins
NOTE: Whenever a release process is broken, Jenkins marks it with a red ball and breaks the build.
Whenever a post-release action went wrong but the release is successful, Jenkins marks the build with a yellow ball and marks the build as unstable.
==== Releasing a Single Project
Let us assume that we are to release `spring-cloud-build` project.
We need to do the following steps:
. Create a branch (for example, `springCloudBuildRelease`) in a project that contains a BOM (for example, https://github.com/spring-cloud/spring-cloud-release/[spring-cloud-release]).
The following example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout -b springCloudBuildRelease
```
. Update *all* versions as if you were doing a release train.
We need to update the project's versions, Boot version, and dependencies versions, too.
Let us assume that we will eventually be doing a release train for the `Hoxton.M1` release, Spring Boot to the latest available one, and `spring-cloud-commons` to `1.2.3.BUILD-SNAPSHOT`.
The following example shows how to do so:
```bash
// setting the release train value
$ ./mvnw versions:set -DnewVersion=Hoxton.M1 -DgenerateBackupPoms=false -DprocessAllModules=true
// Update all parent versions
$ ./mvnw versions:update-parent -DgenerateBackupPoms=false -DprocessAllModules=true
// Setting the necessary dependencies
$ ./mvnw versions:set-property -Dproperty=spring-cloud-commons.version -DnewVersion=1.2.3.BUILD-SNAPSHOT -pl spring-cloud-dependencies -DgenerateBackupPoms=false
// NOTE!!!
// Verify that the versions set by Maven are correct!!
$ git diff
// commit and push the branch
$ git add . && git commit -m "Updating project for Spring Cloud Build release" && git push origin springCloudBuildRelease
```
IMPORTANT: If you're doing a e.g. `M1` release, remember to not have any snapshot versions in this branch.
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], which the following image shows:
image::{github-raw}/docs/src/main/asciidoc/images/releasers.png[Releaser view]
. Pick the proper releaser project (for example, `spring-cloud-build-releaser`).
The following image shows the settings for this example:
image::{github-raw}/docs/src/main/asciidoc/images/scBuildReleaser.png[Spring Cloud Build Releaser - build with parameters]
. Next, click `Build with parameters`.
The following image shows the UI for doing so:
image::{github-raw}/docs/src/main/asciidoc/images/runningScBuildReleaser.png[Updated `RELEASER_POM_BRANCH`]
Pick from which branch you would like the project (for example, `spring-cloud-build` - defaults to `master`) to be built and update the `RELEASER_POM_BRANCH` to point to the checked-out branch of Spring Cloud Release (for example, `springCloudBuildRelease`).
You can pick whether you want to perform only post-release tasks or the whole release.
. Finally, click `Build`.
You are done!
As a post action, do not forget to remove the branch.
The following example shows how to do so:
```bash
// to synchronize any deleted branches (don't run this if you want leave any deleted branches that were deleted in the origin)
$ git fetch -p
$ git branch -d springCloudBuildRelease
$ git push origin --delete springCloudBuildRelease
```
==== Releasing a Release Train
We call a release train a `meta-release`.
In order to perform one, you need to:
. In your project (which must contain a BOM, such as `spring-cloud-release`) you have to have a branch, where you store properties with versions of your projects.
For example, the branch name can be https://github.com/spring-cloud/spring-cloud-release/tree/jenkins-releaser-config[jenkins-releaser-config]).
The folloiwng example shows how to do so:
```bash
$ git clone git@github.com:spring-cloud/spring-cloud-release.git
$ cd spring-cloud-release
$ git checkout jenkins-releaser-config
```
. Create a file that contains all properties for a given release train.
The name of the release train should be lowercase, and dots should be converted to underscores.
For example, for the `Greenwich.SR2` release train we need to have a file named `greenwich_sr2.properties`.
The following example shows how to do so:
```bash
$ touch greenwich_sr2.properties
```
. We need to update the file with all versions for the release train.
The properties file contains an *ordered* list of `releaser.fixed-versions[project-name]=project-version` entries, as the following listing shows:
```bash
$ echo "releaser.fixed-versions[spring-boot]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-build]=2.1.5.RELEASE
releaser.fixed-versions[spring-cloud-commons]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-function]=2.0.2.RELEASE
releaser.fixed-versions[spring-cloud-stream]=Fishtown.SR3
releaser.fixed-versions[spring-cloud-aws]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-bus]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-task]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-config]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-netflix]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-cloudfoundry]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-kubernetes]=1.0.2.RELEASE
releaser.fixed-versions[spring-cloud-openfeign]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-consul]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gateway]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-security]=2.1.3.RELEASE
releaser.fixed-versions[spring-cloud-sleuth]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-zookeeper]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-contract]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-gcp]=1.1.2.RELEASE
releaser.fixed-versions[spring-cloud-vault]=2.1.2.RELEASE
releaser.fixed-versions[spring-cloud-release]=Greenwich.SR2" >> greenwich_sr2.properties
$ git add greenwich_sr2.properties && git commit -m "Added Greenwich.SR2 properties" && git push origin jenkins-releaser-config
```
Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], as the following image shows:
image::{github-raw}/docs/src/main/asciidoc/images/releasersForMetaRelease.png[Releaser view]
. Pick the proper meta-releaser project (for example, `spring-cloud-meta-releaser`), as the following image shows:
image::{github-raw}/docs/src/main/asciidoc/images/springCloudMetaRelease.png[Spring Cloud Meta Releaser - build with parameters]
. Next, click `Build with parameters`.
image::{github-raw}/docs/src/main/asciidoc/images/runningSpringCloudMetaReleaser.png[Spring Cloud Meta Releaser view]
You have quite a few options to pick, but the most important one is to set the value of the `RELEASE_VERSION` to the given release train version (for example, `Greenwich.SR2`).
Continue updating the rest of the fields if necessary and read the field descriptions and this documentation for more information.
. Finally, click `Build`.
You are done!
=== FAQ
==== JSchException: Auth fail