From 516edbe9df3e6b7ecf5591f08e93a134502c2e70 Mon Sep 17 00:00:00 2001 From: buildmaster Date: Tue, 30 Oct 2018 11:00:34 +0000 Subject: [PATCH] Sync docs from master to gh-pages --- multi/multi__spring_cloud_release_tools.html | 4 ++-- single/spring-cloud-release-tools.html | 4 ++-- spring-cloud-release-tools.xml | 16 ++++++++++++++-- 3 files changed, 18 insertions(+), 6 deletions(-) diff --git a/multi/multi__spring_cloud_release_tools.html b/multi/multi__spring_cloud_release_tools.html index 5412e425..4b9f2419 100644 --- a/multi/multi__spring_cloud_release_tools.html +++ b/multi/multi__spring_cloud_release_tools.html @@ -2,7 +2,7 @@ 1. Spring Cloud Release Tools
1. Spring Cloud Release Tools
Prev   

1. Spring Cloud Release Tools

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.

1.1 What does it do?

1.1.1 Single project

For a single project

  • Clones the Spring Cloud Release project and picks all versions (Boot + Cloud projects)

  • Modifies the project versions with values from a BOM (e.g. for Spring Cloud it’s Spring Cloud Release)

    • throws an exception when we bump versions to release and there’s a SNAPSHOT version referenced in the POM

  • Performs the build and checks if the docs modules have properly created the documentation

    • throws an exception when in the docs module there’s an unresolved tag in any HTML file
  • Commits changed poms (ONLY FOR NON-SNAPSHOT VERSIONS)
  • Creates a tag for the release / milestone (ONLY FOR NON-SNAPSHOT VERSIONS)
  • Runs the deployment of the artifacts
  • Publishes the docs (to spring-cloud-static for non-snapshots, to gh-pages for snapshots)
  • Reverts back to snapshots, bumps the version by a patch (1.0.1.RELEASE → 1.0.2.BUILD-SNAPSHOT) (ONLY FOR RELEASE VERSIONS)
  • Closes the milestone on Github (e.g. v1.0.1.RELEASE) (ONLY FOR NON-SNAPSHOT VERSIONS)
[Important]Important

Starting with version that does Sagan integration, you MUST pass the OAuth token, -otherwise the application will fail to start

After project release

1.1.2 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
[Important]Important

For the meta-releaser to work we assume that the path to the +otherwise the application will fail to start

After project release

1.1.2 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)
[Important]Important

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

1.2 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
@@ -115,7 +115,7 @@ or build only tasks with names spring-cloud-build,spring-c
 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].

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

    • 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.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.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 Spring Project page 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.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. +train depends on projects that got already released. We default this list to [spring-boot, spring-cloud-stream, spring-cloud-task].

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

    • 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.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.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.sagan.update-sagan - 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 and run the the build. 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.
    • 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. diff --git a/single/spring-cloud-release-tools.html b/single/spring-cloud-release-tools.html index ef3348e6..b5915e39 100644 --- a/single/spring-cloud-release-tools.html +++ b/single/spring-cloud-release-tools.html @@ -2,7 +2,7 @@ Spring Cloud Release Tools

      Spring Cloud Release Tools

      Table of Contents

      1. Spring Cloud Release Tools
      1.1. What does it do?
      1.1.1. Single project
      1.1.2. Meta-release
      1.2. What should I do first?
      1.3. How to run it (interactive mode)
      1.4. How to run it (automatic mode)
      1.5. How to run meta-release (automatic-mode)
      1.6. Project options
      1.7. Examples
      1.7.1. Keeping configuration in the project
      1.7.2. Specifying A Branch
      1.7.3. Using Environment Variables
      1.8. FAQ
      1.8.1. JSchException: Auth fail

      1. Spring Cloud Release Tools

      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.

      1.1 What does it do?

      1.1.1 Single project

      For a single project

      • Clones the Spring Cloud Release project and picks all versions (Boot + Cloud projects)

      • Modifies the project versions with values from a BOM (e.g. for Spring Cloud it’s Spring Cloud Release)

        • throws an exception when we bump versions to release and there’s a SNAPSHOT version referenced in the POM

      • Performs the build and checks if the docs modules have properly created the documentation

        • throws an exception when in the docs module there’s an unresolved tag in any HTML file
      • Commits changed poms (ONLY FOR NON-SNAPSHOT VERSIONS)
      • Creates a tag for the release / milestone (ONLY FOR NON-SNAPSHOT VERSIONS)
      • Runs the deployment of the artifacts
      • Publishes the docs (to spring-cloud-static for non-snapshots, to gh-pages for snapshots)
      • Reverts back to snapshots, bumps the version by a patch (1.0.1.RELEASE → 1.0.2.BUILD-SNAPSHOT) (ONLY FOR RELEASE VERSIONS)
      • Closes the milestone on Github (e.g. v1.0.1.RELEASE) (ONLY FOR NON-SNAPSHOT VERSIONS)
      [Important]Important

      Starting with version that does Sagan integration, you MUST pass the OAuth token, -otherwise the application will fail to start

      After project release

      1.1.2 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
      [Important]Important

      For the meta-releaser to work we assume that the path to the +otherwise the application will fail to start

      After project release

      1.1.2 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)
      [Important]Important

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

      1.2 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
@@ -115,7 +115,7 @@ or build only tasks with names spring-cloud-build,spring-c
 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].

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

    • 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.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.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 Spring Project page 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.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. +train depends on projects that got already released. We default this list to [spring-boot, spring-cloud-stream, spring-cloud-task].

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

    • 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.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.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.sagan.update-sagan - 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 and run the the build. 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.
    • 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. diff --git a/spring-cloud-release-tools.xml b/spring-cloud-release-tools.xml index e13936e7..e305d63c 100644 --- a/spring-cloud-release-tools.xml +++ b/spring-cloud-release-tools.xml @@ -4,7 +4,7 @@ Spring Cloud Release Tools -2018-10-29 +2018-10-30 Spring Cloud Release Tools @@ -115,6 +115,9 @@ otherwise the application will fail to start 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 @@ -344,7 +347,10 @@ train depends on projects that got already released. We default this list to
    • 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 Spring Project page with the current release train values. Defaults to true. +releaser.sagan.update-sagan - 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. @@ -353,6 +359,12 @@ train depends on projects that got already released. We default this list to
    • 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.