# spring-cloud-release-tools **Repository Path**: mirrors_spring-cloud/spring-cloud-release-tools ## Basic Information - **Project Name**: spring-cloud-release-tools - **Description**: Tools used for the Spring Cloud release process - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2020-08-18 - **Last Updated**: 2025-08-23 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README //// DO NOT EDIT THIS FILE. IT WAS GENERATED. Manual changes to this file will be lost when it is generated again. Edit the files in the src/main/asciidoc/ directory instead. //// :jdkversion: 1.8 :org: spring-cloud :repo: spring-cloud-release-tools :branch: main image::https://github.com/{org}/{repo}/workflows/Build/badge.svg?style=svg["Build",link="https://github.com/{org}/{repo}/actions"] == 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. === Releasing through Jenkins NOTE: Whenever a release process is broken, Jenkins marks it with a red 'X' and breaks the build. Whenever a post-release action went wrong but the release is successful, Jenkins marks the build with a yellow exclamation and marks the build as unstable. ==== Releasing a Single Project Let us assume that we are to release `spring-cloud-build` project. We need to do the following steps: . Create a branch (for example, `springCloudBuildRelease`) in a project that contains a BOM (for example, https://github.com/spring-cloud/spring-cloud-release/[spring-cloud-release]). The following example shows how to do so: ```bash $ git clone git@github.com:spring-cloud/spring-cloud-release.git $ cd spring-cloud-release $ git checkout -b springCloudBuildRelease ``` . Update *all* versions as if you were doing a release train. We need to update the project's versions, Boot version, and dependencies versions, too. Let us assume that we will eventually be doing a release train for the `Hoxton.M1` release, Spring Boot to the latest available one, and `spring-cloud-commons` to `1.2.3.BUILD-SNAPSHOT`. The following example shows how to do so: ```bash // setting the release train value $ ./mvnw versions:set -DnewVersion=Hoxton.M1 -DgenerateBackupPoms=false -DprocessAllModules=true // Update all parent versions $ ./mvnw versions:update-parent -DgenerateBackupPoms=false -DprocessAllModules=true // Setting the necessary dependencies $ ./mvnw versions:set-property -Dproperty=spring-cloud-commons.version -DnewVersion=1.2.3.BUILD-SNAPSHOT -pl spring-cloud-dependencies -DgenerateBackupPoms=false // NOTE!!! // Verify that the versions set by Maven are correct!! $ git diff // commit and push the branch $ git add . && git commit -m "Updating project for Spring Cloud Build release" && git push origin springCloudBuildRelease ``` IMPORTANT: If you're doing a e.g. `M1` release, remember to not have any snapshot versions in this branch. Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], which the following image shows: image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/releasers.png[Releaser view] . Pick the proper releaser project (for example, `spring-cloud-build-releaser`). The following image shows the settings for this example: image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/scBuildReleaser.png[Spring Cloud Build Releaser - build with parameters] . Next, click `Build with parameters`. The following image shows the UI for doing so: image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/runningScBuildReleaser.png[Updated `RELEASER_POM_BRANCH`] Pick from which branch you would like the project (for example, `spring-cloud-build` - defaults to `main`) to be built and update the `RELEASER_POM_BRANCH` to point to the checked-out branch of Spring Cloud Release (for example, `springCloudBuildRelease`). You can pick whether you want to perform only post-release tasks or the whole release. . Finally, click `Build`. You are done! As a post action, do not forget to remove the branch. The following example shows how to do so: ```bash // to synchronize any deleted branches (don't run this if you want leave any deleted branches that were deleted in the origin) $ git fetch -p $ git branch -d springCloudBuildRelease $ git push origin --delete springCloudBuildRelease ``` ==== Releasing a Release Train We call a release train a `meta-release`. In order to perform one, you need to: . In your project (which must contain a BOM, such as `spring-cloud-release`) you have to have a branch, where you store properties with versions of your projects. For example, the branch name can be https://github.com/spring-cloud/spring-cloud-release/tree/jenkins-releaser-config[jenkins-releaser-config]). The following example shows how to do so: ```bash $ git clone git@github.com:spring-cloud/spring-cloud-release.git $ cd spring-cloud-release $ git checkout jenkins-releaser-config ``` . Create a file that contains all properties for a given release train. The name of the release train should be lowercase, and dots should be converted to underscores. For example, for the `Greenwich.SR2` release train we need to have a file named `greenwich_sr2.properties`. The following example shows how to do so: ```bash $ touch greenwich_sr2.properties ``` . We need to update the file with all versions for the release train. The properties file contains an *ordered* list of `releaser.fixed-versions[project-name]=project-version` entries, as the following listing shows: ```bash $ echo "releaser.fixed-versions[spring-boot]=2.1.5.RELEASE releaser.fixed-versions[spring-cloud-build]=2.1.5.RELEASE releaser.fixed-versions[spring-cloud-commons]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-function]=2.0.2.RELEASE releaser.fixed-versions[spring-cloud-stream]=Fishtown.SR3 releaser.fixed-versions[spring-cloud-aws]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-bus]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-task]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-config]=2.1.3.RELEASE releaser.fixed-versions[spring-cloud-netflix]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-cloudfoundry]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-kubernetes]=1.0.2.RELEASE releaser.fixed-versions[spring-cloud-openfeign]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-consul]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-gateway]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-security]=2.1.3.RELEASE releaser.fixed-versions[spring-cloud-sleuth]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-zookeeper]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-contract]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-gcp]=1.1.2.RELEASE releaser.fixed-versions[spring-cloud-vault]=2.1.2.RELEASE releaser.fixed-versions[spring-cloud-release]=Greenwich.SR2" >> greenwich_sr2.properties $ git add greenwich_sr2.properties && git commit -m "Added Greenwich.SR2 properties" && git push origin jenkins-releaser-config ``` Since the project is prepared, go to Jenkins and select the https://jenkins.spring.io/view/Spring%20Cloud/view/Releaser/[Releaser view], as the following image shows: image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/releasersForMetaRelease.png[Releaser view] . Pick the proper meta-releaser project (for example, `spring-cloud-meta-releaser`), as the following image shows: image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/springCloudMetaRelease.png[Spring Cloud Meta Releaser - build with parameters] . Next, click `Build with parameters`. image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/runningSpringCloudMetaReleaser.png[Spring Cloud Meta Releaser view] You have quite a few options to pick, but the most important one is to set the value of the `RELEASE_VERSION` to the given release train version (for example, `Greenwich.SR2`). Continue updating the rest of the fields if necessary and read the field descriptions and this documentation for more information. . Finally, click `Build`. You are done! === What does it do? ==== Single project For a single project, by default if you opt in to all tasks - Clones the BOM project and picks all versions - 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 (for Spring Cloud 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: Starting with version that does Sagan integration, you MUST pass the OAuth token, otherwise the application will fail to start After project release - Generates an email template under `target/email.txt` (ONLY FOR NON-SNAPSHOT VERSIONS) - Generates a blog template under `target/blog.md` (ONLY FOR NON-SNAPSHOT VERSIONS) - Generates a tweet template under `target/tweet.txt` (ONLY FOR NON-SNAPSHOT VERSIONS) - Generates a release notes template under `target/notes.md` (ONLY FOR NON-SNAPSHOT VERSIONS) - Updates project information in Sagan (https://spring.io) (ONLY FOR SNAPSHOT / RELEASE VERSIONS) - 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 documentation links (for Spring Cloud https://github.com/spring-cloud/spring-cloud-static/tree/gh-pages/current) - Will update the release train project page (for Spring Cloud it will be `https://github.com/spring-projects/spring-cloud`) ==== Meta-release All the tasks are opt in, so if you do opt in for everything you'll get: - 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 `main` 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: For the meta-releaser to work we assume that the path to the custom configuration file for each project is always `config/releaser.yml`. NOTE: If you want to run some projects in parallel you have to set the `releaser.meta-release.release-groups` property to state which projects should be released in parallel. Example: ```properties releaser.meta-release.release-groups[0]=projectA,projectB,projectC ``` If in the list of projects you have `projectA,projectB,projectC,projectD,projectE`, then `projectA,projectB,projectC` will be released in parallel and then `projectD` and `projectE` sequentially. === How can I extend it? The project consists of the following main modules * `releaser-core` - with the core logic for doing releases * `relaser-spring` - with the Spring setup of tasks and a flow execution * `projects` ** where each project has their configuration properties and additional tasks You can create your own project's module and * if you want to completely rewrite the flow of the release, just set `releaser.flow.default-enabled` to `false` and create the whole flow from scratch * if you want to modify the current flow, you can add new tasks by just creating a bean of a given type that extends the `ReleaserTask` and set its order accordingly. Example of creating a new `ReleaseReleaserTask` called `BuildCustomStuffTask`: ```java package releaser.my_project; //... import releaser.internal.Releaser; import releaser.internal.spring.Arguments; import releaser.internal.spring.ExecutionResult; import releaser.internal.tasks.ReleaseReleaserTask; @Component public class BuildCustomStuffTask implements ReleaseReleaserTask { /** * Order of this task. The higher value, the lower order. */ public static final int ORDER = 45; @Override public String name() { return "build_custom_stuff"; } @Override public String shortName() { return "bcf"; } @Override public String header() { return "BUILDING CUSTOM STUFF"; } @Override public String description() { return "Builds custom stuff"; } @Override public ExecutionResult runTask(Arguments args) { // do some custom stuff basing on the arguments return ExecutionResult.success(); } @Override public int getOrder() { return BuildCustomStuffTask.ORDER; } } ``` Each release or post release task can implement one of the following interfaces * `ReleaserTask` - marker interface for all release tasks * `ReleaseReleaserTask` - if a task is part of the main release process. That means that if it breaks, the whole release process should stop at once. * `PostReleaseReleaserTask` - marker interface for a post release task. If a post release task fails - the build continues but will be unstable. * `SingleProjectReleaserTask` - a release task for a single project. * `ProjectPostReleaseReleaserTask` - a post release task for a single project. * `DryRunReleaseReleaserTask` - a release task that should be executed during dry run mode. * `TrainPostReleaseReleaserTask` - a post release task that should be executed after the whole release train. * `CompositeReleaserTask` - a task that delegates work to other tasks. In addition, your project can provide the following beans: * `CustomBomParser` - if you need to perform some additional BOM parsing. E.g. Spring Cloud adds `spring-boot` and `spring-cloud-build` versions when parsing the BOM project. * `CustomProjectDocumentationUpdater` - if you need to perform some custom logic when updating the project's documentation. * `CustomGithubIssues` - if you need to perform additional logic when dealing with Github issues. To run the project you should create your main class preferably under the `releaser` package and extend the `ReleaserCommandLineRunner` class. ```java package releaser; import releaser.internal.options.Parser; import releaser.internal.spring.ExecutionResultHandler; import releaser.internal.spring.SpringReleaser; import org.springframework.boot.SpringApplication; import org.springframework.boot.WebApplicationType; import org.springframework.boot.autoconfigure.SpringBootApplication; @SpringBootApplication public class ReleaserApplication extends ReleaserCommandLineRunner { public ReleaserApplication(SpringReleaser releaser, ExecutionResultHandler executionResultHandler, Parser parser) { super(releaser, executionResultHandler, parser); } public static void main(String[] args) { SpringApplication application = new SpringApplication(ReleaserApplication.class); application.setWebApplicationType(WebApplicationType.NONE); application.run(args); } } ``` You can also extend the way the projects and tasks are parsed, flows are executed and the result is analyzed together with the printed report. To do that you should implement the following interfaces as beans: * `SpringReleaser` - performs the release, given the provided options * `FlowRunner` - knows how to execute a release and post release flow * `ExecutionResultHandler` - handles the result of the release === 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 [source,bash] ---- $ git clone git@github.com:spring-cloud/spring-cloud-release-tools.git $ cd spring-cloud-release-tools $ ./mvnw clean install ---- IMPORTANT: 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) [source,bash] ---- $ 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/projects/spring-cloud/target/spring-cloud-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. TIP: 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 [source] ---- === 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. TIP: 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. [source,bash] ---- $ 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/releaser-spring/target/releaser-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 [source,bash] ---- 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 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 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 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 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 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) [source,bash] ---- $ 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/releaser-spring/target/releaser-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) [source,bash] ---- $ java -jar ~/repo/spring-cloud-release-tools/releaser-spring/target/releaser-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 [source,bash] ---- $ java -jar ~/repo/spring-cloud-release-tools/releaser-spring/target/releaser-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) [source,bash] ---- $ java -jar ~/repo/spring-cloud-release-tools/releaser-spring/target/releaser-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) [source,bash] ---- $ java -jar ~/repo/spring-cloud-release-tools/releaser-spring/target/releaser-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) [source,bash] ---- $ java -jar ~/repo/spring-cloud-release-tools/releaser-spring/target/releaser-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 projects/spring-cloud/target/spring-cloud-1.0.0.BUILD-SNAPSHOT.jar --spring.config.name=releaser -x=true --"releaser.fixed-versions[spring-cloud-sleuth]=2.0.1.BUILD-SNAPSHOT" ``` IMPORTANT: 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. |=== |Name | Default | Description |releaser.antora.spring-docs-actions-tag | | Tag for Spring Docs Actions repo. |releaser.antora.spring-docs-actions-url | | URL to Spring Docs Actions repo. |releaser.antora.spring-docs-ssh-host-key | | |releaser.antora.spring-docs-ssh-key-path | | |releaser.antora.spring-docs-ssh-username | | |releaser.antora.sync-antora-docs-command | | Command to sync Antora docs. |releaser.bash.build-command | `+++echo "{{systemProps}}"+++` | Command to be executed to build the project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.bash.deploy-command | `+++echo "{{systemProps}}"+++` | Command to be executed to deploy a built project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.bash.deploy-guides-command | `+++echo "{{systemProps}}"+++` | Command to be executed to build and deploy guides project only. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.bash.generate-release-train-docs-command | `+++echo "{{version}}"+++` | Command to be executed to generate release train documentation. |releaser.bash.publish-docs-command | `+++mkdir -p target && echo "{{version}}"+++` | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.bash.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.bundles.create-project-release-bundle | `+++false+++` | |releaser.bundles.create-release-train-release-bundle | `+++false+++` | |releaser.bundles.distribute-project-release-bundle | `+++false+++` | |releaser.bundles.distribute-release-train-source-bundle | `+++false+++` | |releaser.bundles.repo-access-token | | |releaser.bundles.repo-url | `+++https://usw1.packages.broadcom.com+++` | |releaser.bundles.repo-username | | |releaser.bundles.repos | | |releaser.commercial | `+++false+++` | |releaser.fixed-versions | | Project name to its version - overrides all versions retrieved from a release train repository like Spring Cloud Release. |releaser.flow.default-enabled | `+++true+++` | Should the default flow of jobs be preserved. If set to {@code false} will not register any jobs as beans, and it will be up to you to set the whole configuration of jobs. |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.cache-directory | | Absolute path to a directory with cache for OkHTTP calls to GitHub. |releaser.git.clone-destination-dir | | Where should the release train repo get cloned to. If {@code null} defaults to a temporary directory. |releaser.git.create-release-notes-for-milestone | `+++false+++` | If set to {@code false}, will not create release notes for milestone. |releaser.git.documentation-branch | | Branch to check out for the documentation project. |releaser.git.documentation-url | | 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.github-changelog-generator-url | `+++https://github.com/spring-io/github-changelog-generator/releases/download/v0.0.8/github-changelog-generator.jar+++` | URL to the fat jar with Github Changelog Generator. |releaser.git.number-of-checked-milestones | `+++50+++` | In order not to iterate endlessly over milestones we introduce a threshold of milestones that we will go through to find the matching milestone. |releaser.git.oauth-token | | GitHub OAuth token to be used to interact with GitHub repo. |releaser.git.org-name | | The organization name on Github. |releaser.git.password | | Optional Git password. If not passed keys will be used for authentication. |releaser.git.release-train-bom-url | | URL to a release train repository. |releaser.git.release-train-branch | | Branch to check out for the release train. |releaser.git.release-train-docs-branch | | Branch to check out for the release train docs. |releaser.git.release-train-docs-url | | URL to the release train documentation. |releaser.git.release-train-wiki-page-prefix | | Page prefix for the release train wiki. E.g. for [Spring-Cloud-Finchley-Release-Notes] it would be [Spring-Cloud]. |releaser.git.release-train-wiki-url | | URL to the release train wiki. |releaser.git.run-updated-samples | `+++false+++` | If set to {@code false}, will not update the test samples. |releaser.git.spring-project-branch | | Branch to check out for the release train project. |releaser.git.spring-project-url | | URL to the release train project page repository. |releaser.git.test-samples-branch | | Branch to check out for the test samples. |releaser.git.test-samples-project-url | | URL to test samples. |releaser.git.update-all-test-samples | `+++false+++` | If set to {@code false}, will not clone and update the samples for all projects. |releaser.git.update-documentation-repo | `+++false+++` | If {@code false}, will not update the documentation repository. |releaser.git.update-github-milestones | `+++false+++` | If set to {@code false}, will not update Github milestones. |releaser.git.update-release-train-docs | `+++false+++` | If set to {@code false}, will not update the release train docs. |releaser.git.update-release-train-wiki | `+++false+++` | If set to {@code false}, will not clone and update the release train wiki. |releaser.git.update-spring-guides | `+++false+++` | If set to {@code false}, will not update Spring Guides for a release train. |releaser.git.update-spring-project | `+++false+++` | 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 | `+++false+++` | 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 --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}+++` | Command to be executed to build the project If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.gradle.deploy-command | `+++./gradlew publish --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}+++` | Command to be executed to deploy a built project. |releaser.gradle.deploy-guides-command | `+++./gradlew clean build deployGuides --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}+++` | Command to be executed to build and deploy guides project only. |releaser.gradle.generate-release-train-docs-command | `+++./gradlew generateReleaseTrainDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}+++` | Command to be executed to generate release train documentation. |releaser.gradle.gradle-props-substitution | | A mapping that should be applied to {@code gradle.properties} in order to perform a substitution of properties. The mapping is from a property inside {@code gradle.properties} to the projects name. Example.

In {@code gradle.properties} you have {@code verifierVersion=1.0.0} . You want this property to get updated with the value of {@code spring-cloud-contract} version. Then it's enough to do the mapping like this for this Releaser's property: {@code verifierVersion=spring-cloud-contract}. |releaser.gradle.ignored-gradle-regex | | List of regular expressions of ignored gradle props. Defaults to test projects and samples. |releaser.gradle.publish-docs-command | `+++./gradlew publishDocs --console=plain -PnextVersion={{nextVersion}} -PoldVersion={{oldVersion}} -PcurrentVersion={{version}} {{systemProps}}+++` | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version. |releaser.gradle.run-antora-command | `+++./gradlew antora {{systemProps}}+++` | Command to be executed to run Antora. |releaser.gradle.system-properties | | Additional system properties that should be passed to the build / deploy commands. If present in other commands "{{systemProps}}" will be substituted with this property. |releaser.gradle.wait-time-in-minutes | `+++20+++` | Max wait time in minutes for the process to finish. |releaser.maven.build-command | `+++./mvnw clean install -B -Pdocs {{systemProps}}+++` | Command to be executed to build the project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.maven.deploy-command | `+++./mvnw deploy -DskipTests -B -Pfast,deploy {{systemProps}}+++` | Command to be executed to deploy a built project. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.maven.deploy-guides-command | `+++./mvnw clean verify deploy -B -Pguides,integration -pl guides {{systemProps}}+++` | Command to be executed to build and deploy guides project only. If present "{{version}}" will be replaced by the provided version. "{{nextVersion}}" with the bumped snapshot version and "{{oldVersion}}" with the version before version updating. |releaser.maven.generate-release-train-docs-command | `+++bash release_train.sh --retrieveversions --version {{version}} --ghpages --auto+++` | Command to be executed to generate release train documentation. |releaser.maven.publish-docs-command | `+++./mvnw deploy -DskipTests -B -Pfast,deploy,docs -pl docs {{systemProps}}+++` | Command to be executed to publish documentation. If present "{{version}}" will be replaced by the provided version. |releaser.maven.run-antora-command | `+++./mvnw antora -Pdocs {{systemProps}}+++` | Command to be executed to run Antora. |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 | | 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-group-thread-count | `+++4+++` | Number of threads per release group. E.g. for thread count of 4 if there are 6 projects in a release group, 4 of them will be executed in parallel and 2 will wait for their turn. |releaser.meta-release.release-group-timeout-in-minutes | `+++180+++` | Timeout in minutes during which we're waiting for a single composite task per a project to be executed. That means that if set to e.g. 180 then a release process for a single project should take at most 180 minutes. |releaser.meta-release.release-groups | | If provided, allows to provide groups of projects that can be ran in parallel. E.g. {@code --releaser.meta-release.release-groups[0]=projectA,projectB,projectC} {@code --releaser.meta-release.release-groups[1]=projectD,projectE} {@code --releaser.meta-release.release-groups[2]=projectF,projectG} The order is still provided by the list of versions passed to the releaser. Basing on that order, and this value we are able to build a flow with projects. |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 | | Name of the release train project. |releaser.pom.bom-version-pattern | | The pattern to match a version property in a BOM. Remember to catch the dependency name in a group. E.g. "^(spring-cloud-.*)\\.version$". |releaser.pom.branch | `+++main+++` | Which branch of release train BOM should be checked out. Defaults to {@code main}. |releaser.pom.ignored-pom-regex | `+++^.*\.git/.*$+++` | List of regular expressions of ignored poms. Defaults to test projects and samples. |releaser.pom.pom-with-boot-starter-parent | | Subfolder of the pom that contains the {@code spring-boot-starer-parent} dependency. |releaser.pom.this-train-bom | | 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://api.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 | `+++false+++` | If set to {@code false} will not update Sagan. |releaser.skip-post-release-tasks | `+++false+++` | If set to {@code true} will not run post release tasks. |releaser.template.enabled | `+++false+++` | Should template generation be enabled. |releaser.template.template-folder | | 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 | | 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. |=== TIP: 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/releaser-spring-1.0.0.M1.jar` Example for application arguments: `java -jar target/releaser-spring-1.0.0.M1.jar --releaser.pom.branch=Camden.SR6` IMPORTANT: 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: [source,bash] ---- $ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/releaser-spring/1.0.0.M1/releaser-spring-1.0.0.M1.jar -O ../releaser-spring-1.0.0.M1.jar $ java -jar target/releaser-spring-1.0.0.M1.jar --spring.config.name=releaser ---- TIP: Notice that we're downloading the jar to a parent folder, not to `target`. That's because `target` get cleaned during the build process IMPORTANT: 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 `main` branch of `spring-cloud-release`. If you would like to use another branch you can specify it using the `releaser.pom.branch` property. [source,bash] ---- $ java -jar releaser-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 [source,bash] ---- $ export RELEASER_POM_BRANCH=Dalston.RELEASE $ export RELEASER_GIT_OAUTH_TOKEN=... $ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/releaser-spring/1.0.0.M1/releaser-spring-1.0.0.M1.jar -O releaser-spring-1.0.0.M1.jar $ java -jar target/releaser-spring-1.0.0.M1.jar --releaser.working-dir=/path/to/project/root ---- === FAQ ==== JSchException: Auth fail You may get an exception similar to the following: [source] ---- 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.(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: [source,bash] ---- # to run the agent $ eval `ssh-agent` # to store the pass in the agent $ ssh-add ~/.ssh/id_rsa ---- ==== Skipping version check If you know what you're doing and want to skip snapshot / milestone version check for poms or any other files, just set the following comment [`@releaser:version-check-off`] in the same line where the version appears. Example: [source,xml] ---- 1.19.2-M2 0.6.12 ---- == Building :jdkversion: 17 === Basic Compile and Test To build the source you will need to install JDK {jdkversion}. Spring Cloud uses Maven for most build-related activities, and you should be able to get off the ground quite quickly by cloning the project you are interested in and typing ---- $ ./mvnw install ---- NOTE: You can also install Maven (>=3.3.3) yourself and run the `mvn` command in place of `./mvnw` in the examples below. If you do that you also might need to add `-P spring` if your local Maven settings do not contain repository declarations for spring pre-release artifacts. NOTE: Be aware that you might need to increase the amount of memory available to Maven by setting a `MAVEN_OPTS` environment variable with a value like `-Xmx512m -XX:MaxPermSize=128m`. We try to cover this in the `.mvn` configuration, so if you find you have to do it to make a build succeed, please raise a ticket to get the settings added to source control. The projects that require middleware (i.e. Redis) for testing generally require that a local instance of [Docker](https://www.docker.com/get-started) is installed and running. === Documentation The spring-cloud-build module has a "docs" profile, and if you switch that on it will try to build asciidoc sources from `src/main/asciidoc`. As part of that process it will look for a `README.adoc` and process it by loading all the includes, but not parsing or rendering it, just copying it to `${main.basedir}` (defaults to `${basedir}`, i.e. the root of the project). If there are any changes in the README it will then show up after a Maven build as a modified file in the correct place. Just commit it and push the change. === Working with the code If you don't have an IDE preference we would recommend that you use https://www.springsource.com/developer/sts[Spring Tools Suite] or https://eclipse.org[Eclipse] when working with the code. We use the https://eclipse.org/m2e/[m2eclipse] eclipse plugin for maven support. Other IDEs and tools should also work without issue as long as they use Maven 3.3.3 or better. ==== Activate the Spring Maven profile Spring Cloud projects require the 'spring' Maven profile to be activated to resolve the spring milestone and snapshot repositories. Use your preferred IDE to set this profile to be active, or you may experience build errors. ==== Importing into eclipse with m2eclipse We recommend the https://eclipse.org/m2e/[m2eclipse] eclipse plugin when working with eclipse. If you don't already have m2eclipse installed it is available from the "eclipse marketplace". NOTE: Older versions of m2e do not support Maven 3.3, so once the projects are imported into Eclipse you will also need to tell m2eclipse to use the right profile for the projects. If you see many different errors related to the POMs in the projects, check that you have an up to date installation. If you can't upgrade m2e, add the "spring" profile to your `settings.xml`. Alternatively you can copy the repository settings from the "spring" profile of the parent pom into your `settings.xml`. ==== Importing into eclipse without m2eclipse If you prefer not to use m2eclipse you can generate eclipse project metadata using the following command: [indent=0] ---- $ ./mvnw eclipse:eclipse ---- The generated eclipse projects can be imported by selecting `import existing projects` from the `file` menu. IMPORTANT: There are 2 different versions of language level used in Spring Cloud Sleuth. Java 1.7 is used for main sources and Java 1.8 is used for tests. When importing your project to an IDE please activate the `ide` Maven profile to turn on Java 1.8 for both main and test sources. Of course remember that you MUST NOT use Java 1.8 features in the main sources. If you do so your app will break during the Maven build. == Spring Cloud Release Process == Spring Cloud Release Process This section contains the instructions on releasiong the Spring Cloud project using the Spring Cloud Releaser. === Before you get started 1. Create the Spring Cloud Release project on your local machine. For example: ```bash git clone git@github.com:spring-cloud/spring-cloud-release.git cd spring-cloud-release ``` [start=2] . Pull all Spring Cloud projects to your local machine so that if there is a problem during release, you can make the tweaks to the affected project quickly. === Spring Cloud Build Releaser Instructions . Go to the spring-cloud-release project and checkout the `jenkins-releaser-config` branch. Then pull the latest from the repository. ```bash cd spring-cloud-release git checkout jenkins-releaser-config git pull origin jenkins-releaser-config ``` [start=2] . Find the most recent release in the desired release train. In this document we will use: 2020_0_x.properties . Create a copy of that file and set the name of the copy to .properties (for example: 2020_0_2.properties) . Edit this file and update all project versions to their latest release. .. The latest release for each project can be determined by navigating to the individual Github project and checking for commits since the last release, where the last release is marked by a commit from spring-cloud-issues. If there are commits since the last release, change the value in the properties file. If there are no commits since the last release (i.e. the last commit is from spring-cloud-issues) then do not increment the value. . Make a note of the projects that did not increment their version number, as those projects will need to be specified later in the “RELEASER_PROJECTS_TO_SKIP” field in the Jenkins project spring-cloud--meta-releaser NOTE: Sometimes the release value for a project will need to be incremented by more than one, for example if there was a release for an individual project due to a CVE and there were commits made after that release. To determine the new version number, look for the latest version in the commit history from spring-cloud-issues. [start=6] . Commit the change . Push the changes back to github. For example: ```bash git push origin jenkins-releaser-config ``` [start=8] . Request that project owners verify versions in the Spring Cloud Slack room by sharing a github link to the 2020_0_x.properties you just pushed. . Now go to the `spring-cloud-build--version-releaser` job on Jenkins. For example: `spring-cloud-build-Kilburn-main-releaser`. NOTE: The builder project is required to run first because it is required for spring-cloud-function and spring-cloud-stream. All other spring-cloud builds will run after spring-cloud-function and spring-cloud-stream have performed a successful release [start=10] . Click `Build With Parameters` on the left side of page image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/build-releaser-buildwithparams.png[Build With Params] [start=11] . In the RELEASE_VERSION column enter the name of the file you created without the properties extension image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/build-releaser-setreleaseversion.png[Set The Version] [start=12] . Click the “DRY_RUN” option and then click `Build` button as shown below: image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/build-releaser-selectdryrun.png[Set Dry Run] [start=13] . Once the dry run is successfully complete we need to remove all of the artifacts from the dry run. To do this select the `spring-cloud-purge-worker-artifacts-releaser` job from the list of jobs. . Once the purge work has completed successfully, . Select Rebuild Last option on the left side of the page. . Now go to the `spring-cloud-build--version-releaser` job on Jenkins , Select the last build . When build page appears click the `Rebuild` option. image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/build-releaser-selectlastrun.png[Select Last Run] [start=18] . Deselect “DRY_RUN” then click the `Build` button. === Full Spring Cloud Release . Once Spring Cloud Stream and Function projects are released verify that all other builds are succeeding . Now go to the `Spring-cloud--meta-releaser` job on Jenkins. For example: `spring-cloud-Kilburn-meta-releaser` . Click `Build With Parameters` on the left side of page image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/meta-releaser-buildwithparameters.png[Build With Params] [start=4] . Update RELEASE_VERSION with the current release and corresponds to the release file. image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/meta-releaser-setreleaseversion.png[Set The Version] [start=5] . Add spring-cloud-build to RELEASER_PROJECTS_TO_SKIP, so it won’t be rebuilt. Also any other projects that did not change in the properties files, add it to the RELEASER_PROJECTS_TO_SKIP so they can be excluded. . Select Dry Run option . Click Build image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/build-releaser-selectdryrun.png[Set Dry Run] TIP: If there is a failure you can launch the build from the failed project. To do this: Click the Rebuild_Last option, then in the START FROM field insert the name of the project. Then click the Build. NOTE: Spring Cloud K8’s Integration tests may time out. Restart the build. Select Rebuild Last option on the left side of the page. [start=8] . Upon a successful "DRY_RUN". . Click "Rebuild Last" option on the left side of the page. image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/meta-releaser-rebuildlast.png[Rebuild Last] [start=10] . When the build page is rendered. . Deselect “DRY_RUN” then click the build button. . Clear the Start_From field . Click Rebuild === Commercial Releases See https://docs.google.com/document/d/10pk6b2Cy0OW9fzFKEHSRIys-2Z_rseqnu7CIYFXnJoM/edit#heading=h.slor8nyo3f1n[this document] from Trevor for more information on the requirement to create release bundles and distribute the release artifacts to the edge repository. ==== Creating and Distributing Release Bundles The releaser will create release bundles for individual project releases as well as when doing a release for the entire release train. Release bundles and distribution of those bundles are disabled by default. To enable the creation of project release bundles set `releaser.bundles.create-project-release-bundle=true`. The task which creates individual project release bundles, `CreateProjectReleaseBundlePostReleaseTask`, is run when doing a release of an individual project AND when doing a release train release. To enable the creation of release train release bundles set `releaser.bundles.distribute-release-train-source-bundle`. The task which creates a release train source bundle, `CreateReleaseTrainReleaseBundlePostReleaseTask`, is run as a release train `PostReleaseTask`. To distribute a project release bundle to the edge repo you must set `releaser.bundles.distribute-project-release-bundle=true`. The task which distributes the release bundle to the edge repo, `DistributeProjectReleaseBundleTask`, runs as a project post release task and runs after `CreateProjectReleaseBundlePostReleaseTask`. Unlike `CreateProjectReleaseBundlePostReleaseTask`, `DistributeProjectReleaseBundleTask` *should not* be run during a release train release. This is because distributing the release train source release bundle will take care of distributing all the individual project release bundles. To distribute a release train source bundle to the edge repo you must set `releaser.bundles.distribute-release-train-source-bundle=true`. The task which distributes release train release source bundles, `DistributeReleaseTrainSourceBundleTask`, runs as a release train post release task. *Release bundles and distribution of those bundles only occurs `releaser.commercial=true`, it is not a snapshot release, and is not a dry run.* NOTE: Distribution of release bundles to the edge repo can only be done on a CI system like Jenkins. ==== Creating and Distributing Release Bundles On Jenkins Our Jenkins jobs have been updated to allow the creation and distribution of release bundles for commercial releases. When releasing individual projects you will see 2 new post release tasks in the job options image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/project_release_bundles.png[Project Release Bundles] When these options are checked the correct properties will be passed to the releaser when run to create and distribute release bundles for an individual project release. If you just want to create and distribute the release bundles for an individual project without doing an entire release make sure the two check boxes are checked and then add `createReleaseBundle,distributeProjectReleaseBundleTask` in the `TASK_NAMES` field and specify the `RELEASE_VERSION` you want to create and distribute the release bundles for. Similar options exist for the Jenkins jobs for the meta-release. image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-release-tools/main/docs/src/main/asciidoc/images/meta_release_release_bundles.png[Release Train Source Release Bundles] If you just want to create the release train source release bundles and distribute them without doing an entire release you can select `RELEASER_POST_RELEASE_ONLY`, uncheck the other post release tasks in the job configuration, but leaving `RELEASER_PUBLISH_RELEASE_BUNDLES` and `DISTRIBUTE_RELEASE_BUNDLES` checked. ==== Verify Distribution Of Artifacts Packages will be distributed to the edge repo at https://packages.broadcom.com/artifactory/spring-enterprise/org/springframework/cloud/[https://packages.broadcom.com/artifactory/spring-enterprise/org/springframework/cloud/]. To authenticate to that repo and verify the artifacts are present follow the instructions here[https://docs.vmware.com/en/Tanzu-Spring-Runtime/Commercial/Tanzu-Spring-Runtime/guide-artifact-repository-administrators.html#access-commercial-subscription]. NOTE: For Broadcom employees access to the Broadcom Customer Support Portal can be found under Okta. == Contributing :spring-cloud-build-branch: master Spring Cloud is released under the non-restrictive Apache 2.0 license, and follows a very standard Github development process, using Github tracker for issues and merging pull requests into master. If you want to contribute even something trivial please do not hesitate, but follow the guidelines below. === Sign the Contributor License Agreement Before we accept a non-trivial patch or pull request we will need you to sign the https://cla.pivotal.io/sign/spring[Contributor License Agreement]. Signing the contributor's agreement does not grant anyone commit rights to the main repository, but it does mean that we can accept your contributions, and you will get an author credit if we do. Active contributors might be asked to join the core team, and given the ability to merge pull requests. === Code of Conduct This project adheres to the Contributor Covenant https://github.com/spring-cloud/spring-cloud-build/blob/{spring-cloud-build-branch}/docs/src/main/asciidoc/code-of-conduct.adoc[code of conduct]. By participating, you are expected to uphold this code. Please report unacceptable behavior to spring-code-of-conduct@pivotal.io. === Code Conventions and Housekeeping None of these is essential for a pull request, but they will all help. They can also be added after the original pull request but before a merge. * Use the Spring Framework code format conventions. If you use Eclipse you can import formatter settings using the `eclipse-code-formatter.xml` file from the https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/spring-cloud-dependencies-parent/eclipse-code-formatter.xml[Spring Cloud Build] project. If using IntelliJ, you can use the https://plugins.jetbrains.com/plugin/6546[Eclipse Code Formatter Plugin] to import the same file. * Make sure all new `.java` files to have a simple Javadoc class comment with at least an `@author` tag identifying you, and preferably at least a paragraph on what the class is for. * Add the ASF license header comment to all new `.java` files (copy from existing files in the project) * Add yourself as an `@author` to the .java files that you modify substantially (more than cosmetic changes). * Add some Javadocs and, if you change the namespace, some XSD doc elements. * A few unit tests would help a lot as well -- someone has to do it. * If no-one else is using your branch, please rebase it against the current master (or other target branch in the main project). * When writing a commit message please follow https://tbaggery.com/2008/04/19/a-note-about-git-commit-messages.html[these conventions], if you are fixing an existing issue please add `Fixes gh-XXXX` at the end of the commit message (where XXXX is the issue number). === Checkstyle Spring Cloud Build comes with a set of checkstyle rules. You can find them in the `spring-cloud-build-tools` module. The most notable files under the module are: .spring-cloud-build-tools/ ---- └── src    ├── checkstyle    │   └── checkstyle-suppressions.xml <3>    └── main    └── resources    ├── checkstyle-header.txt <2>    └── checkstyle.xml <1> ---- <1> Default Checkstyle rules <2> File header setup <3> Default suppression rules ==== Checkstyle configuration Checkstyle rules are *disabled by default*. To add checkstyle to your project just define the following properties and plugins. .pom.xml ---- true <1> true <2> true <3> <4> io.spring.javaformat spring-javaformat-maven-plugin <5> org.apache.maven.plugins maven-checkstyle-plugin <5> org.apache.maven.plugins maven-checkstyle-plugin ---- <1> Fails the build upon Checkstyle errors <2> Fails the build upon Checkstyle violations <3> Checkstyle analyzes also the test sources <4> Add the Spring Java Format plugin that will reformat your code to pass most of the Checkstyle formatting rules <5> Add checkstyle plugin to your build and reporting phases If you need to suppress some rules (e.g. line length needs to be longer), then it's enough for you to define a file under `${project.root}/src/checkstyle/checkstyle-suppressions.xml` with your suppressions. Example: .projectRoot/src/checkstyle/checkstyle-suppresions.xml ---- ---- It's advisable to copy the `${spring-cloud-build.rootFolder}/.editorconfig` and `${spring-cloud-build.rootFolder}/.springformat` to your project. That way, some default formatting rules will be applied. You can do so by running this script: ```bash $ curl https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/.editorconfig -o .editorconfig $ touch .springformat ``` === IDE setup ==== Intellij IDEA In order to setup Intellij you should import our coding conventions, inspection profiles and set up the checkstyle plugin. The following files can be found in the https://github.com/spring-cloud/spring-cloud-build/tree/master/spring-cloud-build-tools[Spring Cloud Build] project. .spring-cloud-build-tools/ ---- └── src    ├── checkstyle    │   └── checkstyle-suppressions.xml <3>    └── main    └── resources    ├── checkstyle-header.txt <2>    ├── checkstyle.xml <1>    └── intellij       ├── Intellij_Project_Defaults.xml <4>       └── Intellij_Spring_Boot_Java_Conventions.xml <5> ---- <1> Default Checkstyle rules <2> File header setup <3> Default suppression rules <4> Project defaults for Intellij that apply most of Checkstyle rules <5> Project style conventions for Intellij that apply most of Checkstyle rules .Code style image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-code-style.png[Code style] Go to `File` -> `Settings` -> `Editor` -> `Code style`. There click on the icon next to the `Scheme` section. There, click on the `Import Scheme` value and pick the `Intellij IDEA code style XML` option. Import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Spring_Boot_Java_Conventions.xml` file. .Inspection profiles image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-inspections.png[Code style] Go to `File` -> `Settings` -> `Editor` -> `Inspections`. There click on the icon next to the `Profile` section. There, click on the `Import Profile` and import the `spring-cloud-build-tools/src/main/resources/intellij/Intellij_Project_Defaults.xml` file. .Checkstyle To have Intellij work with Checkstyle, you have to install the `Checkstyle` plugin. It's advisable to also install the `Assertions2Assertj` to automatically convert the JUnit assertions image::https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/{spring-cloud-build-branch}/docs/src/main/asciidoc/images/intellij-checkstyle.png[Checkstyle] Go to `File` -> `Settings` -> `Other settings` -> `Checkstyle`. There click on the `+` icon in the `Configuration file` section. There, you'll have to define where the checkstyle rules should be picked from. In the image above, we've picked the rules from the cloned Spring Cloud Build repository. However, you can point to the Spring Cloud Build's GitHub repository (e.g. for the `checkstyle.xml` : `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle.xml`). We need to provide the following variables: - `checkstyle.header.file` - please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/main/resources/checkstyle-header.txt` URL. - `checkstyle.suppressions.file` - default suppressions. Please point it to the Spring Cloud Build's, `spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` file either in your cloned repo or via the `https://raw.githubusercontent.com/spring-cloud/spring-cloud-build/master/spring-cloud-build-tools/src/checkstyle/checkstyle-suppressions.xml` URL. - `checkstyle.additional.suppressions.file` - this variable corresponds to suppressions in your local project. E.g. you're working on `spring-cloud-contract`. Then point to the `project-root/src/checkstyle/checkstyle-suppressions.xml` folder. Example for `spring-cloud-contract` would be: `/home/username/spring-cloud-contract/src/checkstyle/checkstyle-suppressions.xml`. IMPORTANT: Remember to set the `Scan Scope` to `All sources` since we apply checkstyle rules for production and test sources. === Duplicate Finder Spring Cloud Build brings along the `basepom:duplicate-finder-maven-plugin`, that enables flagging duplicate and conflicting classes and resources on the java classpath. ==== Duplicate Finder configuration Duplicate finder is *enabled by default* and will run in the `verify` phase of your Maven build, but it will only take effect in your project if you add the `duplicate-finder-maven-plugin` to the `build` section of the projecst's `pom.xml`. .pom.xml [source,xml] ---- org.basepom.maven duplicate-finder-maven-plugin ---- For other properties, we have set defaults as listed in the https://github.com/basepom/duplicate-finder-maven-plugin/wiki[plugin documentation]. You can easily override them but setting the value of the selected property prefixed with `duplicate-finder-maven-plugin`. For example, set `duplicate-finder-maven-plugin.skip` to `true` in order to skip duplicates check in your build. If you need to add `ignoredClassPatterns` or `ignoredResourcePatterns` to your setup, make sure to add them in the plugin configuration section of your project: [source,xml] ---- org.basepom.maven duplicate-finder-maven-plugin org.joda.time.base.BaseDateTime .*module-info changelog.txt ----