From f70567aa053148591d39e73608b0559b9c4ead66 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Mon, 8 Feb 2021 17:49:11 +0100 Subject: [PATCH] updated the docs --- README.adoc | 299 +++++++++--------- docs/src/main/asciidoc/_configprops.adoc | 8 +- .../asciidoc/spring-cloud-release-tools.adoc | 286 ++++++++--------- 3 files changed, 300 insertions(+), 293 deletions(-) diff --git a/README.adoc b/README.adoc index 97f3eb6e..e5486987 100644 --- a/README.adoc +++ b/README.adoc @@ -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 diff --git a/docs/src/main/asciidoc/_configprops.adoc b/docs/src/main/asciidoc/_configprops.adoc index 4554a7ab..1f93ab64 100644 --- a/docs/src/main/asciidoc/_configprops.adoc +++ b/docs/src/main/asciidoc/_configprops.adoc @@ -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? diff --git a/docs/src/main/asciidoc/spring-cloud-release-tools.adoc b/docs/src/main/asciidoc/spring-cloud-release-tools.adoc index 2639c80b..4152e2f5 100644 --- a/docs/src/main/asciidoc/spring-cloud-release-tools.adoc +++ b/docs/src/main/asciidoc/spring-cloud-release-tools.adoc @@ -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