From d65d50004f5b1b7f35926f31fba8d2914e859fa8 Mon Sep 17 00:00:00 2001 From: Marcin Grzejszczak Date: Fri, 27 Sep 2019 13:43:32 +0200 Subject: [PATCH] Sync docs from master to gh-pages --- reference/html/README.html | 543 ++++--- reference/html/index.html | 1302 +++++++++++++++++ .../html/spring-cloud-release-tools.html | 541 ++++--- 3 files changed, 2043 insertions(+), 343 deletions(-) create mode 100644 reference/html/index.html diff --git a/reference/html/README.html b/reference/html/README.html index d83b09f0..395fc78b 100644 --- a/reference/html/README.html +++ b/reference/html/README.html @@ -238,6 +238,9 @@ otherwise the application will fail to start

For GA/ SR release will create an issue in Spring Guides under https://github.com/spring-guides/getting-started-guides/issues/

  • +

    For GA/ SR release will create an issue in start.spring.io under https://github.com/spring-io/start.spring.io/issues/

    +
    • +

  • For GA/ SR release will update the links under https://github.com/spring-cloud/spring-cloud-static/tree/gh-pages/current

  • @@ -552,179 +555,375 @@ or build only tasks with names spring-cloud-build,spring-cloud-sleuth

    Project options

    -
    -
      -
    • -

      releaser.fixed-versions - A String to String mapping of manually set versions. E.g. "spring-cloud-cli" → "1.0.0.RELEASE" will set -the spring-cloud-cli.version to 1.0.0.RELEASE regardless of what was set in spring-cloud-release project. Example --releaser.fixed-versions[spring-cloud-cli]=1.0.0.RELEASE. -Use these properties to provide versions for the meta release.

      -
      • -
    • -

      releaser.meta-release.enabled - You have to turn it on to enable a meta release. Defaults to false

      -
      • -
    • -

      releaser.meta-release.git-org-url - The URL of the Git organization. We’ll append each project’s name to it. -Defaults to https://github.com/spring-cloud

      -
      • -
    • -

      releaser.meta-release.projects-to-skip - List of projects that we should not clone and release. Spring Cloud release -train depends on projects that got already released. We default this list to [spring-boot, spring-cloud-stream, spring-cloud-task].

      -
      • -
    • -

      releaser.git.update-documentation-repo - If true then will update documentation repository with the current URL. Defaults to true.

      -
      • -
    • -

      releaser.git.spring-project-url - URL to the documentation Git repository. Defaults to https://github.com/spring-projects/spring-cloud.

      -
      • -
    • -

      releaser.git.spring-project-branch - Branch to check out for the documentation project. Defaults to gh-pages.

      -
      • -
    • -

      releaser.git.update-spring-project - If true then will update Project Sagan with the current release train values. Defaults to true.

      -
      • -
    • -

      releaser.git.test-samples-project-url - URL to the test samples to be checked against the given release train. Defaults to https://github.com/spring-cloud/spring-cloud-core-tests.

      -
      • -
    • -

      releaser.git.test-samples-project-branch - Branch to check out for test samples. Defaults to master.

      -
      • -
    • -

      releaser.git.release-train-wiki-url - URL to the project’s release train wiki page. Defaults to https://github.com/spring-projects/spring-cloud.wiki.git.

      -
      • -
    • -

      releaser.git.update-release-train-wiki - If true then will update the release train wiki page with the current release train values. Defaults to true.

      -
      • -
    • -

      releaser.git.run-updated-samples - If true then will update samples and run the the build. Defaults to true.

      -
      • -
    • -

      releaser.git.all-test-samples-urls - URLs to the test samples to be cloned and updated with proper snapshot versions. -E.g. "--releaser.git.all-test-samples-urls[spring-cloud-sleuth]=https://github.com/spring-cloud-samples/sleuth-issues/,https://github.com/spring-cloud-samples/sleuth-documentation-apps/". -Defaults to Sleuth and Contract samples.

      -
      • -
    • -

      releaser.git.update-all-test-samples - If true then will update samples with bumped snapshots after release. Defaults to true.

      -
      • -
    • -

      releaser.git.release-train-docs-url - URL to the release train documentation. Defaults to https://github.com/spring-cloud-sample/scripts.

      -
      • -
    • -

      releaser.git.release-train-docs-branch - Branch to check out for release train documentation. Defaults to master.

      -
      • -
    • -

      releaser.git.update-release-train-docs - If true then will update the release train documentation project and run the generation. Defaults to true.

      -
      • -
    • -

      releaser.git.update-spring-guides - If true then will update Spring Guides with the current release train. Defaults to true.

      -
      • -
    -
    -

    The following properties are used for both meta release and a release of an individual module.

    -
    -
    -
      -
    • -

      releaser.post-release-tasks-only - If set to true will run only post release tasks. Defaults to false.

      -
      • -
    • -

      releaser.meta-release.release-train-project-name - Name of the project that represents the BOM of the release train. Defaults to spring-cloud-release.

      -
      • -
    • -

      releaser.meta-release.release-train-dependency-names - Names of the projects that should be updated with the version of the release train. Defaults to [spring-cloud, spring-cloud-dependencies, spring-cloud-starter].

      -
      • -
    • -

      releaser.git.fetch-versions-from-git - If true then should fill the map of versions from Git. If false then picks fixed versions.

      -
      • -
    • -

      releaser.git.clone-destination-dir - Where should the Spring Cloud Release repo get cloned to. If null defaults to a temporary directory.

      -
      • -
    • -

      releaser.git.release-train-bom-url - URL to a project containing a BOM. Defaults to Spring Cloud Release Git repository: https://github.com/spring-cloud/spring-cloud-release.

      -
      • -
    • -

      releaser.git.documentation-url - URL to the documentation Git repository. Defaults to https://github.com/spring-cloud/spring-cloud-static.

      -
      • -
    • -

      releaser.git.documentation-branch - Branch to check out for the documentation project. Defaults to gh-pages.

      -
      • -
    • -

      releaser.sagan.update-sagan - If true then will update project sagan with information about this project. Defaults to true.

      -
      • -
    • -

      releaser.sagan.docs-adocs-file - Folder with asciidoctor files for docs. Defaults to docs/src/main/asciidoc.

      -
      • -
    • -

      releaser.sagan.index-section-file-name - Name of the ascii doc file with core part of this project’s Sagan project page. Will search under releaser.sagan.docs-adocs-file folder. Defaults to sagan-index.adoc.

      -
      • -
    • -

      releaser.sagan.boot-section-file-name - Name of the ascii doc file with boot part of this project’s Sagan project page. Will search under releaser.sagan.docs-adocs-file folder. Defaults to sagan-boot.adoc.

      -
      • -
    • -

      releaser.git.oauth-token - GitHub OAuth token to be used to interact with GitHub repo.

      -
      • -
    • -

      releaser.git.username - Optional Git username. If not passed keys will be used for authentication.

      -
      • -
    • -

      releaser.git.password - Optional Git password. If not passed keys will be used for authentication.

      -
      • -
    • -

      releaser.git.number-of-checked-milestones - In order not to iterate endlessly over milestones we introduce a threshold of milestones that -we will go through to find the matching milestone. Defaults to 10.

      -
      • -
    • -

      releaser.maven.build-command - Command to be executed to build the project. Defaults to ./mvnw clean install -Pdocs.

      -
      • -
    • -

      releaser.maven.deploy-command - Command to be executed to deploy a built project". Defaults to ./mvnw deploy -DskipTests -Pfast.

      -
      • -
    • -

      releaser.maven.publish-docs-commands - Command to be executed to deploy a built project. If present {{version}} will be replaced by the proper version. -Defaults to the standard Spring Cloud wget and execution of ghpages.

      -
      • -
    • -

      releaser.maven.system-properties - Additional system properties that should be passed to any commands. If present {{systemProps}} will be replaced by the contents of this property.

      -
      • -
    • -

      releaser.maven.wait-time-in-minutes - Max wait time in minutes for the process to finish. Defaults to 20.

      -
      • -
    • -

      releaser.gradle.gradle-props-substitution - a map containing a key which is a property key inside gradle.properties and a value of -a project name. E.g. in gradle.properties you have foo=1.0.0.BUILD-SNAPSHOT and you would like spring-cloud-contract version to -be set there. Just provide a mapping for the gradle-props-substition looking like this foo=spring-cloud-contract and the result -(e.g for sc-contract version 2.0.0.RELEASE) will be an updated gradle.properties with entry foo=2.0.0.RELEASE.

      -
      • -
    • -

      releaser.pom.branch - Which branch of Spring Cloud Release should be checked out. Defaults to master.

      -
      • -
    • -

      releaser.pom.pom-with-boot-starter-parent - What is the location of the pom.xml that contains the spring-boot-starter-parent as its parent pom. Defaults to spring-cloud-starter-parent/pom.xml.

      -
      • -
    • -

      releaser.pom.this-train-bom - What is the location of the pom.xml that contains all the versions for the release train. Defaults to spring-cloud-dependencies/pom.xml.

      -
      • -
    • -

      releaser.pom.bom-version-pattern - Regular expression that will match the versions of projects in the BOM pom.xml. Defaults to ^(spring-cloud-.*)\.version$.

      -
      • -
    • -

      releaser.pom.ignored-pom-regex - List of regular expressions of ignored poms. Defaults to test projects and samples. -Example: "--releaser.pom.ignored-pom-regex=".*\\.git/.*$,.{asterisk}spring-cloud-contract-maven-plugin/src/test/projects/.*$,.*spring-cloud-contract-maven-plugin/target/.*$,.*samples/standalone/[a-z]+/.*$".

      -
      • -
    • -

      releaser.working-dir - By default Releaser assumes running the program from the current working directory.

      -
      • -
    • -

      releaser.template.template-folder - Tells which subfolder with templates to pick for blog, email etc. generation. Defaults to cloud.

      -
      • -
    • -

      releaser.versions.all-versions-file-url - Url to a file containing all the versions. Defaults to YAML from start.spring.io.

      -
      • -
    • -

      releaser.versions.bom-name - Name in the YAML from initilizr for BOM mappings. Defaults to spring-cloud.

      -
      • -
    +

    Below you can find a table with all the releaser options.

    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDefaultDescription

    releaser.bash.build-command

    echo "{{systemProps}}"

    Command to be executed to build the project.

    releaser.bash.deploy-command

    echo "{{systemProps}}"

    Command to be executed to deploy a built project.

    releaser.bash.deploy-guides-command

    echo "{{systemProps}}"

    Command to be executed to build and deploy guides project only.

    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.

    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.

    releaser.git.all-test-sample-urls

    Project to urls mapping. For each project will clone the test project and will update its versions.

    releaser.git.clone-destination-dir

    Where should the release train repo get cloned to. If {@code null} defaults to a temporary directory.

    releaser.git.documentation-branch

    gh-pages

    Branch to check out for the documentation project.

    releaser.git.documentation-url

    https://github.com/spring-cloud/spring-cloud-static

    URL to the documentation Git repository.

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

    Optional Git password. If not passed keys will be used for authentication.

    releaser.git.release-train-bom-url

    https://github.com/spring-cloud/spring-cloud-release

    URL to a release train repository.

    releaser.git.release-train-docs-branch

    master

    Branch to check out for the release train docs.

    releaser.git.release-train-docs-url

    https://github.com/spring-cloud-samples/scripts

    URL to the release train documentation.

    releaser.git.release-train-wiki-page-prefix

    Spring-Cloud

    Page prefix for the release train wiki. E.g. for [Spring-Cloud-Finchley-Release-Notes] it would be [Spring-Cloud].

    releaser.git.release-train-wiki-url

    https://github.com/spring-projects/spring-cloud.wiki

    URL to the release train wiki.

    releaser.git.run-updated-samples

    true

    If set to {@code false}, will not update the test samples.

    releaser.git.spring-project-branch

    gh-pages

    Branch to check out for the release train project.

    releaser.git.spring-project-url

    https://github.com/spring-projects/spring-cloud

    URL to the release train project page repository.

    releaser.git.test-samples-branch

    master

    Branch to check out for the test samples.

    releaser.git.test-samples-project-url

    https://github.com/spring-cloud/spring-cloud-core-tests

    URL to test samples.

    releaser.git.update-all-test-samples

    true

    If set to {@code false}, will not clone and update the samples for all projects.

    releaser.git.update-documentation-repo

    true

    If {@code false}, will not update the documentation repository.

    releaser.git.update-release-train-docs

    true

    If set to {@code false}, will not update the release train docs.

    releaser.git.update-release-train-wiki

    true

    If set to {@code false}, will not clone and update the release train wiki.

    releaser.git.update-spring-guides

    true

    If set to {@code false}, will not update Spring Guides for a release train.

    releaser.git.update-spring-project

    true

    If set to {@code false}, will not update the Spring Project for a release train. E.g. for Spring Cloud will not update https://cloud.spring.io .

    releaser.git.update-start-spring-io

    true

    If set to {@code false}, will not update start.spring.io for a release train.

    releaser.git.username

    Optional Git username. If not passed keys will be used for authentication.

    releaser.gradle.build-command

    ./gradlew clean build publishToMavenLocal {{systemProps}}

    Command to be executed to build the project.

    releaser.gradle.deploy-command

    ./gradlew clean build publish {{systemProps}}

    Command to be executed to deploy a built project.

    releaser.gradle.deploy-guides-command

    ./gradlew clean build deployGuides {{systemProps}}

    Command to be executed to build and deploy guides project only.

    releaser.gradle.generate-release-train-docs-command

    echo 'TODO'

    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

    [echo 'TODO']

    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.

    releaser.maven.deploy-command

    ./mvnw deploy -DskipTests -B -Pfast,deploy {{systemProps}}

    Command to be executed to deploy a built project.

    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.

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

    releaser.meta-release.git-org-url

    https://github.com/spring-cloud

    The URL of the Git organization. We’ll append each project’s name to it.

    releaser.meta-release.projects-to-skip

    Names of projects to skip deployment for meta-release.

    releaser.meta-release.release-train-dependency-names

    All the names of dependencies that should be updated with the release train project version.

    releaser.meta-release.release-train-project-name

    spring-cloud-release

    Name of the release train project.

    releaser.pom.bom-version-pattern

    ^(spring-cloud-.*)\.version$

    The pattern to match a version property in a BOM.

    releaser.pom.branch

    master

    Which branch of release train BOM should be checked out. Defaults to {@code master}.

    releaser.pom.ignored-pom-regex

    List of regular expressions of ignored poms. Defaults to test projects and samples.

    releaser.pom.pom-with-boot-starter-parent

    spring-cloud-starter-parent/pom.xml

    Subfolder of the pom that contains the {@code spring-boot-starer-parent} dependency.

    releaser.pom.this-train-bom

    spring-cloud-dependencies/pom.xml

    Subfolder of the pom that contains the versions for the release train.

    releaser.post-release-tasks-only

    false

    If set to {@code true} will run only post release tasks.

    releaser.sagan.base-url

    https://spring.io

    URL to the Sagan API.

    releaser.sagan.boot-section-file-name

    sagan-boot.adoc

    Name of the ascii doc file with boot part of this project’s Sagan project page. Linked with {@link this#docsAdocsFile}.

    releaser.sagan.docs-adocs-file

    docs/src/main/asciidoc

    Folder with asciidoctor files for docs.

    releaser.sagan.index-section-file-name

    sagan-index.adoc

    Name of the ascii doc file with core part of this project’s Sagan project page. Linked with {@link this#docsAdocsFile}.

    releaser.sagan.update-sagan

    true

    If set to {@code false} will not update Sagan.

    releaser.template.template-folder

    cloud

    Folder in which blog, email etc. templates are stored.

    releaser.versions.all-versions-file-url

    https://raw.githubusercontent.com/spring-io/start.spring.io/master/start-site/src/main/resources/application.yml

    Url to a file containing all the versions. Defaults to YAML from start.spring.io.

    releaser.versions.bom-name

    spring-cloud

    Name in the YAML from initilizr for BOM mappings.

    releaser.working-dir

    By default Releaser assumes running the program from the current working directory. If you want to change this behaviour - just change this value.

    @@ -1547,7 +1746,7 @@ The following files can be found in the
    + + + + +
    + + +Starting with version that does Sagan integration, you MUST pass the OAuth token, +otherwise the application will fail to start +
    +
    +
    +

    After project release

    +
    +
    + +
    +
    +
    +

    Meta-release

    +
    +
      +
    • +

      Uses the fixed versions to clone and check out each project (e.g. spring-cloud-sleuth: 2.1.0.RELEASE)

      +
      • +
    • +

      From the version analyzes the branch and checks it out. E.g.

      +
      +
        +
      • +

        for spring-cloud-release’s `Finchley.RELEASE version will resolve either Finchley branch or will fallback to master if there’s no Finchley branch.

        +
        • +
      • +

        for spring-cloud-sleuth’s `2.1.0.RELEASE version will resolve 2.1.x branch

        +
        • +
      +
      +
      • +
    • +

      Performs the release tasks per each project

      +
      • +
    • +

      Performs the post release tasks at the end of the release

      +
      • +
    • +

      Will update and run smoke test samples (for Spring Cloud it will be https://github.com/spring-cloud/spring-cloud-core-tests)

      +
      • +
    • +

      Will clone provided test samples and will update all versions to the latest ones

      +
      • +
    • +

      Will clone the release train wiki and update it with the latest release versions (for Spring Cloud it will be https://github.com/spring-projects/spring-cloud.wiki.git)

      +
      • +
    +
    +
    + + + + + +
    + + +For the meta-releaser to work we assume that the path to the +custom configuration file for each project is always config/releaser.yml. +
    +
    +
    + +
    +

    What should I do first?

    +
    +

    Members of the Spring Cloud Team typically use this tool as follows. They first +clone the releaser locally and build the jar manually

    +
    +
    +
    +
    $ git clone git@github.com:spring-cloud/spring-cloud-release-tools.git
+$ cd spring-cloud-release-tools
+$ ./mvnw clean install
    +
    +
    +
    + + + + + +
    + + +You must set the value of the OAuth token. You can do it either via +the command line --releaser.git.oauth-token=…​ or put it as an env variable in .bashrc +or .zshrc e.g. export RELEASER_GIT_OAUTH_TOKEN=…​ +
    +
    +
    +
    +

    How to run it (interactive mode)

    +
    +

    Go to your project (e.g. Spring Cloud Sleuth)

    +
    +
    +
    +
    $ git clone git@github.com:spring-cloud/spring-cloud-sleuth.git
+$ cd spring-cloud-sleuth
+$ # example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAPSHOT version of the releaser
+$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser
    +
    +
    +
    +

    The application will start running from your working directory. Running this code +follows the convention that you have the OAuth token environment variable set. It also assumes +that you might have some custom configuration in config/releaser.yml file. This setting is optional - if +you don’t have that file, nothing will happen.

    +
    +
    + + + + + +
    + + +It is important that you clone the repository you are going to release using SSH in order for the +releaser to be able to push tags and commit changes automatically. +
    +
    +
    +

    You will see text similar to this one

    +
    +
    +
    +
    === WHAT DO YOU WANT TO DO? ===
+
+0) Perform a full release of this project without interruptions
+1) Perform a full release of this project in a verbose mode (you'll be asked about skipping steps)
+2) Update poms with versions from Spring Cloud Release
+3) Build the project
+4) Commit, tag and push the tag
+5) Deploy the artifacts
+6) Publish the docs
+7) Go back to snapshots and bump originalVersion by patch
+8) Push the commits
+9) Close the milestone at Github
+10) Create email / blog / tweet etc. templates
+
+You can pick a range of options by using the hyphen - e.g. '2-4' will execute jobs [2,3,4]
+You can execute all tasks starting from a job by using a hyphen and providing only one number - e.g. '8-' will execute jobs [8,9,10]
+You can execute given tasks by providing a comma separated list of tasks - e.g. '3,7,8' will execute jobs [3,7,8]
+
+You can press 'q' to quit
    +
    +
    +
    +

    Just pick a number and continue! Pick either a full release or single steps. You can also pick +ranges or multiple steps. You can also provide the range only with the starting step +- that you will execute all steps starting from the given one.

    +
    +
    + + + + + +
    + + +Read before picking a number cause it might have changed between tool releases ;) +
    +
    +
    +
    +

    How to run it (automatic mode)

    +
    +

    Go to your project (e.g. Spring Cloud Sleuth) and execute the application with -h or --help +flag.

    +
    +
    +
    +
    $ git clone git@github.com:spring-cloud/spring-cloud-sleuth.git
+$ cd spring-cloud-sleuth
+$ # example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAPSHOT version of the releaser
+$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -h
    +
    +
    +
    +

    You will see a help screen looking like more or less like this

    +
    +
    +
    +
    Here you can find the list of tasks in order
+
+[release,releaseVerbose,metaRelease,postRelease,updatePoms,build,commit,deploy,docs,snapshots,push,closeMilestone,updateSagan,createTemplates,updateGuides,updateDocumentation]
+
+
+Option                                Description
+------                                -----------
+-a, --start-from <String>             Starts all release task starting from the
+                                        given task. Requires passing the task
+                                        name (either one letter or the full
+                                        name)
+-b, --build [String]                  Build the project
+-c, --commit [String]                 Commit, tag and push the tag
+-d, --deploy [String]                 Deploy the artifacts
+-f, --full-release [Boolean]          Do you want to do the full release of a
+                                        single project? (default: false)
+-g, --updateSagan [String]            Updating Sagan with release info
+-h, --help [String]
+-i, --interactive <Boolean>           Do you want to set the properties from
+                                        the command line of a single project?
+                                        (default: true)
+-m, --closeMilestone [String]         Close the milestone at Github
+-o, --docs [String]                   Publish the docs
+-p, --push [String]                   Push the commits
+-r, --range <String>                  Runs release tasks from the given range.
+                                        Requires passing the task names with a
+                                        hyphen. The first task is inclusive,
+                                        the second inclusive. E.g. 's-m' would
+                                        mean running 'snapshot', 'push' and
+                                        'milestone' tasks
+-s, --snapshots [String]              Go back to snapshots and bump
+                                        originalVersion by patch
+-t, --createTemplates [String]        Create email / blog / tweet etc. templates
+--task-names, --tn <String>           Starts all release task for the given
+                                        task names
+-u, --updatePoms [String]             Update poms with versions from Spring
+                                        Cloud Release
+--ud, --updateDocumentation [String]  Updating documentation repository
+--ug, --updateGuides [String]         Updating Spring Guides
+-x, --meta-release <Boolean>          Do you want to do the meta release?
+                                        (default: false)
+
+Examples of usage:
+
+Run 'build' & 'commit' & 'deploy'
+java -jar jar.jar -b -c -d
+
+Start from 'push'
+java -jar releaser.jar -a push
+
+Range 'docs' -> 'push'
+java -jar releaser.jar -r o-p
    +
    +
    +
    +

    The Releaser can use two sets of options. The configuration options like releaser.pom.branch +and the task switches. For the tasks you can use either the full names or short switches. For example + providing range of tasks via switches o-p is equivalent to full name docs-push.

    +
    +
    +

    A couple of examples:

    +
    +
    +
    Doing the full release in interactive mode (asking for skipping steps)
    +
    +
    $ git clone git@github.com:spring-cloud/spring-cloud-sleuth.git
+$ cd spring-cloud-sleuth
+$ # example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAPSHOT version of the releaser
+$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser --full-release
    +
    +
    +
    +
    Doing the full release in non interactive mode (automatic release)
    +
    +
    $ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser --full-release --interactive=false
    +
    +
    +
    +
    Updating pom, closing milestone & createTemplates in interactive mode
    +
    +
    $ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -u -m -t
    +
    +
    +
    +
    Running all tasks starting from 'push' (automatic)
    +
    +
    $ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -a push -i=false
    +
    +
    +
    +
    Running tasks from 'docs' (inclusive) to 'push' (inclusive) (automatic)
    +
    +
    $ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -r d-p -i=false
    +
    +
    +
    +
    Running single task 'closeMilestone' (automatic)
    +
    +
    $ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser --closeMilestone -i=false
    +
    +
    +
    +
    +

    How to run meta-release (automatic-mode)

    +
    +

    All you have to do is run the jar with the releaser and pass the +-x=true option to turn on meta-release and a list of fixed versions +in the `--"releaser.fixed-versions[project-name]=project-version" format

    +
    +
    +
    +
    $ java -jar spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --spring.config.name=releaser -x=true --"releaser.fixed-versions[spring-cloud-sleuth]=2.0.1.BUILD-SNAPSHOT"
    +
    +
    +
    + + + + + +
    + + +For the meta release the startFrom or taskNames take into consideration +the project names, not task names. E.g. you can start from spring-cloud-netflix project, +or build only tasks with names spring-cloud-build,spring-cloud-sleuth. +
    +
    +
    +
    +

    Project options

    +
    +

    Below you can find a table with all the releaser options.

    +
    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDefaultDescription

    releaser.bash.build-command

    echo "{{systemProps}}"

    Command to be executed to build the project.

    releaser.bash.deploy-command

    echo "{{systemProps}}"

    Command to be executed to deploy a built project.

    releaser.bash.deploy-guides-command

    echo "{{systemProps}}"

    Command to be executed to build and deploy guides project only.

    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.

    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.

    releaser.git.all-test-sample-urls

    Project to urls mapping. For each project will clone the test project and will update its versions.

    releaser.git.clone-destination-dir

    Where should the release train repo get cloned to. If {@code null} defaults to a temporary directory.

    releaser.git.documentation-branch

    gh-pages

    Branch to check out for the documentation project.

    releaser.git.documentation-url

    https://github.com/spring-cloud/spring-cloud-static

    URL to the documentation Git repository.

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

    Optional Git password. If not passed keys will be used for authentication.

    releaser.git.release-train-bom-url

    https://github.com/spring-cloud/spring-cloud-release

    URL to a release train repository.

    releaser.git.release-train-docs-branch

    master

    Branch to check out for the release train docs.

    releaser.git.release-train-docs-url

    https://github.com/spring-cloud-samples/scripts

    URL to the release train documentation.

    releaser.git.release-train-wiki-page-prefix

    Spring-Cloud

    Page prefix for the release train wiki. E.g. for [Spring-Cloud-Finchley-Release-Notes] it would be [Spring-Cloud].

    releaser.git.release-train-wiki-url

    https://github.com/spring-projects/spring-cloud.wiki

    URL to the release train wiki.

    releaser.git.run-updated-samples

    true

    If set to {@code false}, will not update the test samples.

    releaser.git.spring-project-branch

    gh-pages

    Branch to check out for the release train project.

    releaser.git.spring-project-url

    https://github.com/spring-projects/spring-cloud

    URL to the release train project page repository.

    releaser.git.test-samples-branch

    master

    Branch to check out for the test samples.

    releaser.git.test-samples-project-url

    https://github.com/spring-cloud/spring-cloud-core-tests

    URL to test samples.

    releaser.git.update-all-test-samples

    true

    If set to {@code false}, will not clone and update the samples for all projects.

    releaser.git.update-documentation-repo

    true

    If {@code false}, will not update the documentation repository.

    releaser.git.update-release-train-docs

    true

    If set to {@code false}, will not update the release train docs.

    releaser.git.update-release-train-wiki

    true

    If set to {@code false}, will not clone and update the release train wiki.

    releaser.git.update-spring-guides

    true

    If set to {@code false}, will not update Spring Guides for a release train.

    releaser.git.update-spring-project

    true

    If set to {@code false}, will not update the Spring Project for a release train. E.g. for Spring Cloud will not update https://cloud.spring.io .

    releaser.git.update-start-spring-io

    true

    If set to {@code false}, will not update start.spring.io for a release train.

    releaser.git.username

    Optional Git username. If not passed keys will be used for authentication.

    releaser.gradle.build-command

    ./gradlew clean build publishToMavenLocal {{systemProps}}

    Command to be executed to build the project.

    releaser.gradle.deploy-command

    ./gradlew clean build publish {{systemProps}}

    Command to be executed to deploy a built project.

    releaser.gradle.deploy-guides-command

    ./gradlew clean build deployGuides {{systemProps}}

    Command to be executed to build and deploy guides project only.

    releaser.gradle.generate-release-train-docs-command

    echo 'TODO'

    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

    [echo 'TODO']

    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.

    releaser.maven.deploy-command

    ./mvnw deploy -DskipTests -B -Pfast,deploy {{systemProps}}

    Command to be executed to deploy a built project.

    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.

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

    releaser.meta-release.git-org-url

    https://github.com/spring-cloud

    The URL of the Git organization. We’ll append each project’s name to it.

    releaser.meta-release.projects-to-skip

    Names of projects to skip deployment for meta-release.

    releaser.meta-release.release-train-dependency-names

    All the names of dependencies that should be updated with the release train project version.

    releaser.meta-release.release-train-project-name

    spring-cloud-release

    Name of the release train project.

    releaser.pom.bom-version-pattern

    ^(spring-cloud-.*)\.version$

    The pattern to match a version property in a BOM.

    releaser.pom.branch

    master

    Which branch of release train BOM should be checked out. Defaults to {@code master}.

    releaser.pom.ignored-pom-regex

    List of regular expressions of ignored poms. Defaults to test projects and samples.

    releaser.pom.pom-with-boot-starter-parent

    spring-cloud-starter-parent/pom.xml

    Subfolder of the pom that contains the {@code spring-boot-starer-parent} dependency.

    releaser.pom.this-train-bom

    spring-cloud-dependencies/pom.xml

    Subfolder of the pom that contains the versions for the release train.

    releaser.post-release-tasks-only

    false

    If set to {@code true} will run only post release tasks.

    releaser.sagan.base-url

    https://spring.io

    URL to the Sagan API.

    releaser.sagan.boot-section-file-name

    sagan-boot.adoc

    Name of the ascii doc file with boot part of this project’s Sagan project page. Linked with {@link this#docsAdocsFile}.

    releaser.sagan.docs-adocs-file

    docs/src/main/asciidoc

    Folder with asciidoctor files for docs.

    releaser.sagan.index-section-file-name

    sagan-index.adoc

    Name of the ascii doc file with core part of this project’s Sagan project page. Linked with {@link this#docsAdocsFile}.

    releaser.sagan.update-sagan

    true

    If set to {@code false} will not update Sagan.

    releaser.template.template-folder

    cloud

    Folder in which blog, email etc. templates are stored.

    releaser.versions.all-versions-file-url

    https://raw.githubusercontent.com/spring-io/start.spring.io/master/start-site/src/main/resources/application.yml

    Url to a file containing all the versions. Defaults to YAML from start.spring.io.

    releaser.versions.bom-name

    spring-cloud

    Name in the YAML from initilizr for BOM mappings.

    releaser.working-dir

    By default Releaser assumes running the program from the current working directory. If you want to change this behaviour - just change this value.

    +
    + + + + + +
    + + +You can pass the options either via system properties or via application arguments. +Example for system properties: java -Dreleaser.pom.branch=Camden.SR6 -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar +Example for application arguments: java -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar --releaser.pom.branch=Camden.SR6 +
    +
    +
    + + + + + +
    + + +For the GA release to be successful, it’s important that if the build / deploy command + run a script (e.g. scripts/foo.sh) then inside foo.sh if you call a Maven build ./mvnw clean install + then remember to pass all arguments of the script there too. E.g. ./mvnw clean install ${@}. That’s because + the releaser will pass any system properties to the build / deploy command, such as system properties + with keys and we need them to be passed inside the command executed by the releaser. +
    +
    +
    +
    +

    Examples

    +
    +

    Keeping configuration in the project

    +
    +

    If your project has some custom configuration (e.g. Spring Cloud Contract needs a script to be executed +to build the project and properly merge the docs) then you can put a file named e.g. releaser.yml under config +folder and run your application like this:

    +
    +
    +
    +
    $ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/spring-cloud-release-tools-spring/1.0.0.M1/spring-cloud-release-tools-spring-1.0.0.M1.jar -O ../spring-cloud-release-tools-spring-1.0.0.M1.jar
+$ java -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar --spring.config.name=releaser
    +
    +
    +
    + + + + + +
    + + +Notice that we’re downloading the jar to a parent folder, not to target. That’s because target get cleaned +during the build process +
    +
    +
    + + + + + +
    + + +For the meta-releaser to work we assume that the path to the +configuration file is always config/releaser.yml. +
    +
    +
    +
    +

    Specifying A Branch

    +
    +

    By deafult the releaser will default to using the master branch of spring-cloud-release. +If you would like to use another branch you can specify it using the releaser.pom.branch property.

    +
    +
    +
    +
    $ java -jar spring-cloud-release-tools-spring-1.0.0.M1.jar --releaser.pom.branch=Camden.SR6
    +
    +
    +
    +
    +

    Using Environment Variables

    +
    +

    In some cases it might be easier to specify environment variables instead of passing parameters to +releaser. For example, you might want to use environment variables if you are going to be +releasing multiple projects, this keeps you from having to specify the same parameters for +each release

    +
    +
    +
    +
    $ export RELEASER_POM_BRANCH=Dalston.RELEASE
+$ export RELEASER_GIT_OAUTH_TOKEN=...
+$ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/spring-cloud-release-tools-spring/1.0.0.M1/spring-cloud-release-tools-spring-1.0.0.M1.jar -O spring-cloud-release-tools-spring-1.0.0.M1.jar
+$ java -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar --releaser.working-dir=/path/to/project/root
    +
    +
    +
    +
    +
    +

    Releasing through Jenkins

    +
    + + + + + +
    + + +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:

    +
    +
    +
      +
    1. +

      Create a branch (for example, springCloudBuildRelease) in a project that contains a BOM (for example, spring-cloud-release). The following example shows how to do so:

      +
      2. +
    +
    +
    +
    +
    $ git clone git@github.com:spring-cloud/spring-cloud-release.git
+$ cd spring-cloud-release
+$ git checkout -b springCloudBuildRelease
    +
    +
    +
    +
      +
    1. +

      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:

      +
      2. +
    +
    +
    +
    +
    // 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
    +
    +
    +
    + + + + + +
    + + +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 Releaser view, which the following image shows:

    +
    +
    +
    +Releaser view +
    +
    +
    +
      +
    1. +

      Pick the proper releaser project (for example, spring-cloud-build-releaser). The following image shows the settings for this example:

      +
      2. +
    +
    +
    +
    +Spring Cloud Build Releaser - build with parameters +
    +
    +
    +
      +
    1. +

      Next, click Build with parameters. The following image shows the UI for doing so:

      +
      2. +
    +
    +
    +
    +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.

    +
    +
    +
      +
    1. +

      Finally, click Build.

      +
      2. +
    +
    +
    +

    You are done!

    +
    +
    +

    As a post action, do not forget to remove the branch. The following example shows how to do so:

    +
    +
    +
    +
    // 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:

    +
    +
    +
      +
    1. +

      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 jenkins-releaser-config). The folloiwng example shows how to do so:

      +
      2. +
    +
    +
    +
    +
    $ git clone git@github.com:spring-cloud/spring-cloud-release.git
+$ cd spring-cloud-release
+$ git checkout jenkins-releaser-config
    +
    +
    +
    +
      +
    1. +

      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:

      +
      2. +
    +
    +
    +
    +
    $ touch greenwich_sr2.properties
    +
    +
    +
    +
      +
    1. +

      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:

      +
      2. +
    +
    +
    +
    +
    $ 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 Releaser view, as the following image shows:

    +
    +
    +
    +Releaser view +
    +
    +
    +
      +
    1. +

      Pick the proper meta-releaser project (for example, spring-cloud-meta-releaser), as the following image shows:

      +
      2. +
    +
    +
    +
    +Spring Cloud Meta Releaser - build with parameters +
    +
    +
    +
      +
    1. +

      Next, click Build with parameters.

      +
      2. +
    +
    +
    +
    +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.

    +
    +
    +
      +
    1. +

      Finally, click Build.

      +
      2. +
    +
    +
    +

    You are done!

    +
    +
    +
    +
    +

    FAQ

    +
    +

    JSchException: Auth fail

    +
    +

    You may get an exception similar to the following:

    +
    +
    +
    +
    Caused by: org.eclipse.jgit.errors.TransportException: git@github.com:spring-cloud/spring-cloud-sleuth.git: Auth fail
+	at org.eclipse.jgit.transport.JschConfigSessionFactory.getSession(JschConfigSessionFactory.java:160) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	at org.eclipse.jgit.transport.SshTransport.getSession(SshTransport.java:137) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	at org.eclipse.jgit.transport.TransportGitSsh$SshPushConnection.<init>(TransportGitSsh.java:322) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	at org.eclipse.jgit.transport.TransportGitSsh.openPush(TransportGitSsh.java:167) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	at org.eclipse.jgit.transport.PushProcess.execute(PushProcess.java:160) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	at org.eclipse.jgit.transport.Transport.push(Transport.java:1275) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	at org.eclipse.jgit.api.PushCommand.call(PushCommand.java:161) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	... 25 common frames omitted
+Caused by: com.jcraft.jsch.JSchException: Auth fail
+	at com.jcraft.jsch.Session.connect(Session.java:512) ~[jsch-0.1.53.jar!/:na]
+	at org.eclipse.jgit.transport.JschConfigSessionFactory.getSession(JschConfigSessionFactory.java:117) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
+	... 31 common frames omitted
    +
    +
    +
    +

    To fix that just call, run the following commands before running the app:

    +
    +
    +
    +
    # to run the agent
+$ eval `ssh-agent`
+# to store the pass in the agent
+$ ssh-add ~/.ssh/id_rsa
    +
    +
    +
    +
    + + + + + + + + + + \ No newline at end of file diff --git a/reference/html/spring-cloud-release-tools.html b/reference/html/spring-cloud-release-tools.html index d86c1a1c..206cb9d7 100644 --- a/reference/html/spring-cloud-release-tools.html +++ b/reference/html/spring-cloud-release-tools.html @@ -228,6 +228,9 @@ otherwise the application will fail to start

    For GA/ SR release will create an issue in Spring Guides under https://github.com/spring-guides/getting-started-guides/issues/

  • +

    For GA/ SR release will create an issue in start.spring.io under https://github.com/spring-io/start.spring.io/issues/

    +
    • +

  • For GA/ SR release will update the links under https://github.com/spring-cloud/spring-cloud-static/tree/gh-pages/current

  • @@ -542,179 +545,375 @@ or build only tasks with names spring-cloud-build,spring-cloud-sleuth

    Project options

    -
    -
      -
    • -

      releaser.fixed-versions - A String to String mapping of manually set versions. E.g. "spring-cloud-cli" → "1.0.0.RELEASE" will set -the spring-cloud-cli.version to 1.0.0.RELEASE regardless of what was set in spring-cloud-release project. Example --releaser.fixed-versions[spring-cloud-cli]=1.0.0.RELEASE. -Use these properties to provide versions for the meta release.

      -
      • -
    • -

      releaser.meta-release.enabled - You have to turn it on to enable a meta release. Defaults to false

      -
      • -
    • -

      releaser.meta-release.git-org-url - The URL of the Git organization. We’ll append each project’s name to it. -Defaults to https://github.com/spring-cloud

      -
      • -
    • -

      releaser.meta-release.projects-to-skip - List of projects that we should not clone and release. Spring Cloud release -train depends on projects that got already released. We default this list to [spring-boot, spring-cloud-stream, spring-cloud-task].

      -
      • -
    • -

      releaser.git.update-documentation-repo - If true then will update documentation repository with the current URL. Defaults to true.

      -
      • -
    • -

      releaser.git.spring-project-url - URL to the documentation Git repository. Defaults to https://github.com/spring-projects/spring-cloud.

      -
      • -
    • -

      releaser.git.spring-project-branch - Branch to check out for the documentation project. Defaults to gh-pages.

      -
      • -
    • -

      releaser.git.update-spring-project - If true then will update Project Sagan with the current release train values. Defaults to true.

      -
      • -
    • -

      releaser.git.test-samples-project-url - URL to the test samples to be checked against the given release train. Defaults to https://github.com/spring-cloud/spring-cloud-core-tests.

      -
      • -
    • -

      releaser.git.test-samples-project-branch - Branch to check out for test samples. Defaults to master.

      -
      • -
    • -

      releaser.git.release-train-wiki-url - URL to the project’s release train wiki page. Defaults to https://github.com/spring-projects/spring-cloud.wiki.git.

      -
      • -
    • -

      releaser.git.update-release-train-wiki - If true then will update the release train wiki page with the current release train values. Defaults to true.

      -
      • -
    • -

      releaser.git.run-updated-samples - If true then will update samples and run the the build. Defaults to true.

      -
      • -
    • -

      releaser.git.all-test-samples-urls - URLs to the test samples to be cloned and updated with proper snapshot versions. -E.g. "--releaser.git.all-test-samples-urls[spring-cloud-sleuth]=https://github.com/spring-cloud-samples/sleuth-issues/,https://github.com/spring-cloud-samples/sleuth-documentation-apps/". -Defaults to Sleuth and Contract samples.

      -
      • -
    • -

      releaser.git.update-all-test-samples - If true then will update samples with bumped snapshots after release. Defaults to true.

      -
      • -
    • -

      releaser.git.release-train-docs-url - URL to the release train documentation. Defaults to https://github.com/spring-cloud-sample/scripts.

      -
      • -
    • -

      releaser.git.release-train-docs-branch - Branch to check out for release train documentation. Defaults to master.

      -
      • -
    • -

      releaser.git.update-release-train-docs - If true then will update the release train documentation project and run the generation. Defaults to true.

      -
      • -
    • -

      releaser.git.update-spring-guides - If true then will update Spring Guides with the current release train. Defaults to true.

      -
      • -
    -
    -

    The following properties are used for both meta release and a release of an individual module.

    -
    -
    -
      -
    • -

      releaser.post-release-tasks-only - If set to true will run only post release tasks. Defaults to false.

      -
      • -
    • -

      releaser.meta-release.release-train-project-name - Name of the project that represents the BOM of the release train. Defaults to spring-cloud-release.

      -
      • -
    • -

      releaser.meta-release.release-train-dependency-names - Names of the projects that should be updated with the version of the release train. Defaults to [spring-cloud, spring-cloud-dependencies, spring-cloud-starter].

      -
      • -
    • -

      releaser.git.fetch-versions-from-git - If true then should fill the map of versions from Git. If false then picks fixed versions.

      -
      • -
    • -

      releaser.git.clone-destination-dir - Where should the Spring Cloud Release repo get cloned to. If null defaults to a temporary directory.

      -
      • -
    • -

      releaser.git.release-train-bom-url - URL to a project containing a BOM. Defaults to Spring Cloud Release Git repository: https://github.com/spring-cloud/spring-cloud-release.

      -
      • -
    • -

      releaser.git.documentation-url - URL to the documentation Git repository. Defaults to https://github.com/spring-cloud/spring-cloud-static.

      -
      • -
    • -

      releaser.git.documentation-branch - Branch to check out for the documentation project. Defaults to gh-pages.

      -
      • -
    • -

      releaser.sagan.update-sagan - If true then will update project sagan with information about this project. Defaults to true.

      -
      • -
    • -

      releaser.sagan.docs-adocs-file - Folder with asciidoctor files for docs. Defaults to docs/src/main/asciidoc.

      -
      • -
    • -

      releaser.sagan.index-section-file-name - Name of the ascii doc file with core part of this project’s Sagan project page. Will search under releaser.sagan.docs-adocs-file folder. Defaults to sagan-index.adoc.

      -
      • -
    • -

      releaser.sagan.boot-section-file-name - Name of the ascii doc file with boot part of this project’s Sagan project page. Will search under releaser.sagan.docs-adocs-file folder. Defaults to sagan-boot.adoc.

      -
      • -
    • -

      releaser.git.oauth-token - GitHub OAuth token to be used to interact with GitHub repo.

      -
      • -
    • -

      releaser.git.username - Optional Git username. If not passed keys will be used for authentication.

      -
      • -
    • -

      releaser.git.password - Optional Git password. If not passed keys will be used for authentication.

      -
      • -
    • -

      releaser.git.number-of-checked-milestones - In order not to iterate endlessly over milestones we introduce a threshold of milestones that -we will go through to find the matching milestone. Defaults to 10.

      -
      • -
    • -

      releaser.maven.build-command - Command to be executed to build the project. Defaults to ./mvnw clean install -Pdocs.

      -
      • -
    • -

      releaser.maven.deploy-command - Command to be executed to deploy a built project". Defaults to ./mvnw deploy -DskipTests -Pfast.

      -
      • -
    • -

      releaser.maven.publish-docs-commands - Command to be executed to deploy a built project. If present {{version}} will be replaced by the proper version. -Defaults to the standard Spring Cloud wget and execution of ghpages.

      -
      • -
    • -

      releaser.maven.system-properties - Additional system properties that should be passed to any commands. If present {{systemProps}} will be replaced by the contents of this property.

      -
      • -
    • -

      releaser.maven.wait-time-in-minutes - Max wait time in minutes for the process to finish. Defaults to 20.

      -
      • -
    • -

      releaser.gradle.gradle-props-substitution - a map containing a key which is a property key inside gradle.properties and a value of -a project name. E.g. in gradle.properties you have foo=1.0.0.BUILD-SNAPSHOT and you would like spring-cloud-contract version to -be set there. Just provide a mapping for the gradle-props-substition looking like this foo=spring-cloud-contract and the result -(e.g for sc-contract version 2.0.0.RELEASE) will be an updated gradle.properties with entry foo=2.0.0.RELEASE.

      -
      • -
    • -

      releaser.pom.branch - Which branch of Spring Cloud Release should be checked out. Defaults to master.

      -
      • -
    • -

      releaser.pom.pom-with-boot-starter-parent - What is the location of the pom.xml that contains the spring-boot-starter-parent as its parent pom. Defaults to spring-cloud-starter-parent/pom.xml.

      -
      • -
    • -

      releaser.pom.this-train-bom - What is the location of the pom.xml that contains all the versions for the release train. Defaults to spring-cloud-dependencies/pom.xml.

      -
      • -
    • -

      releaser.pom.bom-version-pattern - Regular expression that will match the versions of projects in the BOM pom.xml. Defaults to ^(spring-cloud-.*)\.version$.

      -
      • -
    • -

      releaser.pom.ignored-pom-regex - List of regular expressions of ignored poms. Defaults to test projects and samples. -Example: "--releaser.pom.ignored-pom-regex=".*\\.git/.*$,.{asterisk}spring-cloud-contract-maven-plugin/src/test/projects/.*$,.*spring-cloud-contract-maven-plugin/target/.*$,.*samples/standalone/[a-z]+/.*$".

      -
      • -
    • -

      releaser.working-dir - By default Releaser assumes running the program from the current working directory.

      -
      • -
    • -

      releaser.template.template-folder - Tells which subfolder with templates to pick for blog, email etc. generation. Defaults to cloud.

      -
      • -
    • -

      releaser.versions.all-versions-file-url - Url to a file containing all the versions. Defaults to YAML from start.spring.io.

      -
      • -
    • -

      releaser.versions.bom-name - Name in the YAML from initilizr for BOM mappings. Defaults to spring-cloud.

      -
      • -
    +

    Below you can find a table with all the releaser options.

    + +++++ + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    NameDefaultDescription

    releaser.bash.build-command

    echo "{{systemProps}}"

    Command to be executed to build the project.

    releaser.bash.deploy-command

    echo "{{systemProps}}"

    Command to be executed to deploy a built project.

    releaser.bash.deploy-guides-command

    echo "{{systemProps}}"

    Command to be executed to build and deploy guides project only.

    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.

    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.

    releaser.git.all-test-sample-urls

    Project to urls mapping. For each project will clone the test project and will update its versions.

    releaser.git.clone-destination-dir

    Where should the release train repo get cloned to. If {@code null} defaults to a temporary directory.

    releaser.git.documentation-branch

    gh-pages

    Branch to check out for the documentation project.

    releaser.git.documentation-url

    https://github.com/spring-cloud/spring-cloud-static

    URL to the documentation Git repository.

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

    Optional Git password. If not passed keys will be used for authentication.

    releaser.git.release-train-bom-url

    https://github.com/spring-cloud/spring-cloud-release

    URL to a release train repository.

    releaser.git.release-train-docs-branch

    master

    Branch to check out for the release train docs.

    releaser.git.release-train-docs-url

    https://github.com/spring-cloud-samples/scripts

    URL to the release train documentation.

    releaser.git.release-train-wiki-page-prefix

    Spring-Cloud

    Page prefix for the release train wiki. E.g. for [Spring-Cloud-Finchley-Release-Notes] it would be [Spring-Cloud].

    releaser.git.release-train-wiki-url

    https://github.com/spring-projects/spring-cloud.wiki

    URL to the release train wiki.

    releaser.git.run-updated-samples

    true

    If set to {@code false}, will not update the test samples.

    releaser.git.spring-project-branch

    gh-pages

    Branch to check out for the release train project.

    releaser.git.spring-project-url

    https://github.com/spring-projects/spring-cloud

    URL to the release train project page repository.

    releaser.git.test-samples-branch

    master

    Branch to check out for the test samples.

    releaser.git.test-samples-project-url

    https://github.com/spring-cloud/spring-cloud-core-tests

    URL to test samples.

    releaser.git.update-all-test-samples

    true

    If set to {@code false}, will not clone and update the samples for all projects.

    releaser.git.update-documentation-repo

    true

    If {@code false}, will not update the documentation repository.

    releaser.git.update-release-train-docs

    true

    If set to {@code false}, will not update the release train docs.

    releaser.git.update-release-train-wiki

    true

    If set to {@code false}, will not clone and update the release train wiki.

    releaser.git.update-spring-guides

    true

    If set to {@code false}, will not update Spring Guides for a release train.

    releaser.git.update-spring-project

    true

    If set to {@code false}, will not update the Spring Project for a release train. E.g. for Spring Cloud will not update https://cloud.spring.io .

    releaser.git.update-start-spring-io

    true

    If set to {@code false}, will not update start.spring.io for a release train.

    releaser.git.username

    Optional Git username. If not passed keys will be used for authentication.

    releaser.gradle.build-command

    ./gradlew clean build publishToMavenLocal {{systemProps}}

    Command to be executed to build the project.

    releaser.gradle.deploy-command

    ./gradlew clean build publish {{systemProps}}

    Command to be executed to deploy a built project.

    releaser.gradle.deploy-guides-command

    ./gradlew clean build deployGuides {{systemProps}}

    Command to be executed to build and deploy guides project only.

    releaser.gradle.generate-release-train-docs-command

    echo 'TODO'

    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

    [echo 'TODO']

    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.

    releaser.maven.deploy-command

    ./mvnw deploy -DskipTests -B -Pfast,deploy {{systemProps}}

    Command to be executed to deploy a built project.

    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.

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

    releaser.meta-release.git-org-url

    https://github.com/spring-cloud

    The URL of the Git organization. We’ll append each project’s name to it.

    releaser.meta-release.projects-to-skip

    Names of projects to skip deployment for meta-release.

    releaser.meta-release.release-train-dependency-names

    All the names of dependencies that should be updated with the release train project version.

    releaser.meta-release.release-train-project-name

    spring-cloud-release

    Name of the release train project.

    releaser.pom.bom-version-pattern

    ^(spring-cloud-.*)\.version$

    The pattern to match a version property in a BOM.

    releaser.pom.branch

    master

    Which branch of release train BOM should be checked out. Defaults to {@code master}.

    releaser.pom.ignored-pom-regex

    List of regular expressions of ignored poms. Defaults to test projects and samples.

    releaser.pom.pom-with-boot-starter-parent

    spring-cloud-starter-parent/pom.xml

    Subfolder of the pom that contains the {@code spring-boot-starer-parent} dependency.

    releaser.pom.this-train-bom

    spring-cloud-dependencies/pom.xml

    Subfolder of the pom that contains the versions for the release train.

    releaser.post-release-tasks-only

    false

    If set to {@code true} will run only post release tasks.

    releaser.sagan.base-url

    https://spring.io

    URL to the Sagan API.

    releaser.sagan.boot-section-file-name

    sagan-boot.adoc

    Name of the ascii doc file with boot part of this project’s Sagan project page. Linked with {@link this#docsAdocsFile}.

    releaser.sagan.docs-adocs-file

    docs/src/main/asciidoc

    Folder with asciidoctor files for docs.

    releaser.sagan.index-section-file-name

    sagan-index.adoc

    Name of the ascii doc file with core part of this project’s Sagan project page. Linked with {@link this#docsAdocsFile}.

    releaser.sagan.update-sagan

    true

    If set to {@code false} will not update Sagan.

    releaser.template.template-folder

    cloud

    Folder in which blog, email etc. templates are stored.

    releaser.versions.all-versions-file-url

    https://raw.githubusercontent.com/spring-io/start.spring.io/master/start-site/src/main/resources/application.yml

    Url to a file containing all the versions. Defaults to YAML from start.spring.io.

    releaser.versions.bom-name

    spring-cloud

    Name in the YAML from initilizr for BOM mappings.

    releaser.working-dir

    By default Releaser assumes running the program from the current working directory. If you want to change this behaviour - just change this value.