530 lines
35 KiB
XML
530 lines
35 KiB
XML
<?xml version="1.0" encoding="UTF-8"?>
|
|
<?asciidoc-toc maxdepth="8"?>
|
|
<?asciidoc-numbered?>
|
|
<book xmlns="http://docbook.org/ns/docbook" xmlns:xl="http://www.w3.org/1999/xlink" version="5.0" xml:lang="en">
|
|
<info>
|
|
<title>Spring Cloud Release Tools</title>
|
|
<date>2019-03-22</date>
|
|
</info>
|
|
<chapter xml:id="_spring_cloud_release_tools">
|
|
<title>Spring Cloud Release Tools</title>
|
|
<simpara>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.</simpara>
|
|
<section xml:id="_what_does_it_do">
|
|
<title>What does it do?</title>
|
|
<section xml:id="_single_project">
|
|
<title>Single project</title>
|
|
<simpara>For a single project</simpara>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>Clones the Spring Cloud Release project and picks all versions (Boot + Cloud projects)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Modifies the project versions with values from a BOM (e.g. for Spring Cloud it’s Spring Cloud Release)</simpara>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>throws an exception when we bump versions to release and there’s a SNAPSHOT version referenced in the POM</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Performs the build and checks if the <literal>docs</literal> modules have properly created the documentation</simpara>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>throws an exception when in the <literal>docs</literal> module there’s an unresolved tag in any HTML file</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Commits changed poms (ONLY FOR NON-SNAPSHOT VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Creates a tag for the release / milestone (ONLY FOR NON-SNAPSHOT VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Runs the deployment of the artifacts</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Publishes the docs (to <literal>spring-cloud-static</literal> for non-snapshots, to <literal>gh-pages</literal> for snapshots)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Reverts back to snapshots, bumps the version by a patch (<literal>1.0.1.RELEASE</literal> → <literal>1.0.2.BUILD-SNAPSHOT</literal>) (ONLY FOR RELEASE VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Closes the milestone on Github (e.g. <literal>v1.0.1.RELEASE</literal>) (ONLY FOR NON-SNAPSHOT VERSIONS)</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<important>
|
|
<simpara>Starting with version that does Sagan integration, you MUST pass the OAuth token,
|
|
otherwise the application will fail to start</simpara>
|
|
</important>
|
|
<simpara>After project release</simpara>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>Generates an email template under <literal>target/email.txt</literal> (ONLY FOR NON-SNAPSHOT VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Generates a blog template under <literal>target/blog.md</literal> (ONLY FOR NON-SNAPSHOT VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Generates a tweet template under <literal>target/tweet.txt</literal> (ONLY FOR NON-SNAPSHOT VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Generates a release notes template under <literal>target/notes.md</literal> (ONLY FOR NON-SNAPSHOT VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Updates project information in Sagan (<link xl:href="https://spring.io">https://spring.io</link>) (ONLY FOR SNAPSHOT / RELEASE VERSIONS)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>For <literal>GA</literal>/ <literal>SR</literal> release will create an issue in Spring Guides under <link xl:href="https://github.com/spring-guides/getting-started-guides/issues/">https://github.com/spring-guides/getting-started-guides/issues/</link></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>For <literal>GA</literal>/ <literal>SR</literal> release will update the links under <link xl:href="https://github.com/spring-cloud/spring-cloud-static/tree/gh-pages/current">https://github.com/spring-cloud/spring-cloud-static/tree/gh-pages/current</link></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Will update the release train project page (for Spring Cloud it will be <literal><link xl:href="https://github.com/spring-projects/spring-cloud">https://github.com/spring-projects/spring-cloud</link></literal>)</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</section>
|
|
<section xml:id="_meta_release">
|
|
<title>Meta-release</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>Uses the fixed versions to clone and check out each project (e.g. <literal>spring-cloud-sleuth: 2.1.0.RELEASE</literal>)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>From the version analyzes the branch and checks it out. E.g.</simpara>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara>for <literal>spring-cloud-release’s `Finchley.RELEASE</literal> version will resolve either <literal>Finchley</literal> branch or will fallback to <literal>master</literal> if there’s no <literal>Finchley</literal> branch.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>for <literal>spring-cloud-sleuth’s `2.1.0.RELEASE</literal> version will resolve <literal>2.1.x</literal> branch</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Performs the release tasks per each project</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Performs the post release tasks at the end of the release</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Will update and run smoke test samples (for Spring Cloud it will be <literal><link xl:href="https://github.com/spring-cloud/spring-cloud-core-tests">https://github.com/spring-cloud/spring-cloud-core-tests</link></literal>)</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Will clone provided test samples and will update all versions to the latest ones</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara>Will clone the release train wiki and update it with the latest release versions (for Spring Cloud it will be <literal><link xl:href="https://github.com/spring-projects/spring-cloud.wiki.git">https://github.com/spring-projects/spring-cloud.wiki.git</link></literal>)</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<important>
|
|
<simpara>For the meta-releaser to work we assume that the path to the
|
|
custom configuration file for each project is always <literal>config/releaser.yml</literal>.</simpara>
|
|
</important>
|
|
</section>
|
|
</section>
|
|
<section xml:id="_what_should_i_do_first">
|
|
<title>What should I do first?</title>
|
|
<simpara>Members of the Spring Cloud Team typically use this tool as follows. They first
|
|
clone the releaser locally and build the jar manually</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ git clone git@github.com:spring-cloud/spring-cloud-release-tools.git
|
|
$ cd spring-cloud-release-tools
|
|
$ ./mvnw clean install</programlisting>
|
|
<important>
|
|
<simpara>You must set the value of the OAuth token. You can do it either via
|
|
the command line <literal>--releaser.git.oauth-token=…​</literal> or put it as an env variable in <literal>.bashrc</literal>
|
|
or <literal>.zshrc</literal> e.g. <literal>export RELEASER_GIT_OAUTH_TOKEN=…​</literal></simpara>
|
|
</important>
|
|
</section>
|
|
<section xml:id="_how_to_run_it_interactive_mode">
|
|
<title>How to run it (interactive mode)</title>
|
|
<simpara>Go to your project (e.g. Spring Cloud Sleuth)</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ git clone git@github.com:spring-cloud/spring-cloud-sleuth.git
|
|
$ cd spring-cloud-sleuth
|
|
$ # example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAPSHOT version of the releaser
|
|
$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser</programlisting>
|
|
<simpara>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 <literal>config/releaser.yml</literal> file. This setting is optional - if
|
|
you don’t have that file, nothing will happen.</simpara>
|
|
<tip>
|
|
<simpara>It is important that you clone the repository you are going to release using SSH in order for the
|
|
<literal>releaser</literal> to be able to push tags and commit changes automatically.</simpara>
|
|
</tip>
|
|
<simpara>You will see text similar to this one</simpara>
|
|
<screen>=== 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</screen>
|
|
<simpara>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.</simpara>
|
|
<tip>
|
|
<simpara>Read before picking a number cause it might have changed between tool releases ;)</simpara>
|
|
</tip>
|
|
</section>
|
|
<section xml:id="_how_to_run_it_automatic_mode">
|
|
<title>How to run it (automatic mode)</title>
|
|
<simpara>Go to your project (e.g. Spring Cloud Sleuth) and execute the application with <literal>-h</literal> or <literal>--help</literal>
|
|
flag.</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ git clone git@github.com:spring-cloud/spring-cloud-sleuth.git
|
|
$ cd spring-cloud-sleuth
|
|
$ # example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAPSHOT version of the releaser
|
|
$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -h</programlisting>
|
|
<simpara>You will see a help screen looking like more or less like this</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered">Here you can find the list of tasks in order
|
|
|
|
[release,releaseVerbose,metaRelease,postRelease,updatePoms,build,commit,deploy,docs,snapshots,push,closeMilestone,updateSagan,createTemplates,updateGuides,updateDocumentation]
|
|
|
|
|
|
Option Description
|
|
------ -----------
|
|
-a, --start-from <String> Starts all release task starting from the
|
|
given task. Requires passing the task
|
|
name (either one letter or the full
|
|
name)
|
|
-b, --build [String] Build the project
|
|
-c, --commit [String] Commit, tag and push the tag
|
|
-d, --deploy [String] Deploy the artifacts
|
|
-f, --full-release [Boolean] Do you want to do the full release of a
|
|
single project? (default: false)
|
|
-g, --updateSagan [String] Updating Sagan with release info
|
|
-h, --help [String]
|
|
-i, --interactive <Boolean> Do you want to set the properties from
|
|
the command line of a single project?
|
|
(default: true)
|
|
-m, --closeMilestone [String] Close the milestone at Github
|
|
-o, --docs [String] Publish the docs
|
|
-p, --push [String] Push the commits
|
|
-r, --range <String> Runs release tasks from the given range.
|
|
Requires passing the task names with a
|
|
hyphen. The first task is inclusive,
|
|
the second inclusive. E.g. 's-m' would
|
|
mean running 'snapshot', 'push' and
|
|
'milestone' tasks
|
|
-s, --snapshots [String] Go back to snapshots and bump
|
|
originalVersion by patch
|
|
-t, --createTemplates [String] Create email / blog / tweet etc. templates
|
|
--task-names, --tn <String> Starts all release task for the given
|
|
task names
|
|
-u, --updatePoms [String] Update poms with versions from Spring
|
|
Cloud Release
|
|
--ud, --updateDocumentation [String] Updating documentation repository
|
|
--ug, --updateGuides [String] Updating Spring Guides
|
|
-x, --meta-release <Boolean> Do you want to do the meta release?
|
|
(default: false)
|
|
|
|
Examples of usage:
|
|
|
|
Run 'build' & 'commit' & 'deploy'
|
|
java -jar jar.jar -b -c -d
|
|
|
|
Start from 'push'
|
|
java -jar releaser.jar -a push
|
|
|
|
Range 'docs' -> 'push'
|
|
java -jar releaser.jar -r o-p</programlisting>
|
|
<simpara>The Releaser can use two sets of options. The configuration options like <literal>releaser.pom.branch</literal>
|
|
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 <literal>o-p</literal> is equivalent to full name <literal>docs-push</literal>.</simpara>
|
|
<simpara>A couple of examples:</simpara>
|
|
<formalpara>
|
|
<title>Doing the full release in interactive mode (asking for skipping steps)</title>
|
|
<para>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ git clone git@github.com:spring-cloud/spring-cloud-sleuth.git
|
|
$ cd spring-cloud-sleuth
|
|
$ # example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAPSHOT version of the releaser
|
|
$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser --full-release</programlisting>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>Doing the full release in non interactive mode (automatic release)</title>
|
|
<para>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser --full-release --interactive=false</programlisting>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>Updating pom, closing milestone & createTemplates in interactive mode</title>
|
|
<para>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -u -m -t</programlisting>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>Running all tasks starting from 'push' (automatic)</title>
|
|
<para>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -a push -i=false</programlisting>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>Running tasks from 'docs' (inclusive) to 'push' (inclusive) (automatic)</title>
|
|
<para>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser -r d-p -i=false</programlisting>
|
|
</para>
|
|
</formalpara>
|
|
<formalpara>
|
|
<title>Running single task 'closeMilestone' (automatic)</title>
|
|
<para>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser --closeMilestone -i=false</programlisting>
|
|
</para>
|
|
</formalpara>
|
|
</section>
|
|
<section xml:id="_how_to_run_meta_release_automatic_mode">
|
|
<title>How to run meta-release (automatic-mode)</title>
|
|
<simpara>All you have to do is run the jar with the releaser and pass the
|
|
<literal>-x=true</literal> option to turn on meta-release and a list of fixed versions
|
|
in the `--"releaser.fixed-versions[project-name]=project-version" format</simpara>
|
|
<screen>$ java -jar spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-1.0.0.BUILD-SNAPSHOT.jar --spring.config.name=releaser -x=true --"releaser.fixed-versions[spring-cloud-sleuth]=2.0.1.BUILD-SNAPSHOT"</screen>
|
|
<important>
|
|
<simpara>For the meta release the <literal>startFrom</literal> or <literal>taskNames</literal> take into consideration
|
|
the project names, not task names. E.g. you can start from <literal>spring-cloud-netflix</literal> project,
|
|
or build only tasks with names <literal>spring-cloud-build,spring-cloud-sleuth</literal>.</simpara>
|
|
</important>
|
|
</section>
|
|
<section xml:id="_project_options">
|
|
<title>Project options</title>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara><literal>releaser.fixed-versions</literal> - A String to String mapping of manually set versions. E.g. <literal>"spring-cloud-cli" → "1.0.0.RELEASE"</literal> will set
|
|
the <literal>spring-cloud-cli.version</literal> to <literal>1.0.0.RELEASE</literal> regardless of what was set in <literal>spring-cloud-release</literal> project. Example <literal>--releaser.fixed-versions[spring-cloud-cli]=1.0.0.RELEASE</literal>.
|
|
Use these properties to provide versions for the meta release.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.meta-release.enabled</literal> - You have to turn it on to enable a meta release. Defaults to <literal>false</literal></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.meta-release.git-org-url</literal> - The URL of the Git organization. We’ll append each project’s name to it.
|
|
Defaults to <literal><link xl:href="https://github.com/spring-cloud">https://github.com/spring-cloud</link></literal></simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.meta-release.projects-to-skip</literal> - 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 <literal>[spring-boot, spring-cloud-stream, spring-cloud-task]</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.update-documentation-repo</literal> - If <literal>true</literal> then will update documentation repository with the <literal>current</literal> URL. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.spring-project-url</literal> - URL to the documentation Git repository. Defaults to <literal><link xl:href="https://github.com/spring-projects/spring-cloud">https://github.com/spring-projects/spring-cloud</link></literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.spring-project-branch</literal> - Branch to check out for the documentation project. Defaults to <literal>gh-pages</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.update-spring-project</literal> - If <literal>true</literal> then will update Project Sagan with the current release train values. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.test-samples-project-url</literal> - URL to the test samples to be checked against the given release train. Defaults to <literal><link xl:href="https://github.com/spring-cloud/spring-cloud-core-tests">https://github.com/spring-cloud/spring-cloud-core-tests</link></literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.test-samples-project-branch</literal> - Branch to check out for test samples. Defaults to <literal>master</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.release-train-wiki-url</literal> - URL to the project’s release train wiki page. Defaults to <literal><link xl:href="https://github.com/spring-projects/spring-cloud.wiki.git">https://github.com/spring-projects/spring-cloud.wiki.git</link></literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.update-release-train-wiki</literal> - If <literal>true</literal> then will update the release train wiki page with the current release train values. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.run-updated-samples</literal> - If <literal>true</literal> then will update samples and run the the build. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.all-test-samples-urls</literal> - URLs to the test samples to be cloned and updated with proper snapshot versions.
|
|
E.g. <literal>"--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/"</literal>.
|
|
Defaults to Sleuth and Contract samples.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.update-all-test-samples</literal> - If <literal>true</literal> then will update samples with bumped snapshots after release. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.release-train-docs-url</literal> - URL to the release train documentation. Defaults to <literal><link xl:href="https://github.com/spring-cloud-sample/scripts">https://github.com/spring-cloud-sample/scripts</link></literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.release-train-docs-branch</literal> - Branch to check out for release train documentation. Defaults to <literal>master</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.update-release-train-docs</literal> - If <literal>true</literal> then will update the release train documentation project and run the generation. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.update-spring-guides</literal> - If <literal>true</literal> then will update Spring Guides with the current release train. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<simpara>The following properties are used for both meta release and a release of an individual module.</simpara>
|
|
<itemizedlist>
|
|
<listitem>
|
|
<simpara><literal>releaser.post-release-tasks-only</literal> - If set to <literal>true</literal> will run only post release tasks. Defaults to <literal>false</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.meta-release.release-train-project-name</literal> - Name of the project that represents the BOM of the release train. Defaults to <literal>spring-cloud-release</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.meta-release.release-train-dependency-names</literal> - Names of the projects that should be updated with the version of the release train. Defaults to <literal>[spring-cloud, spring-cloud-dependencies, spring-cloud-starter]</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.fetch-versions-from-git</literal> - If <literal>true</literal> then should fill the map of versions from Git. If <literal>false</literal> then picks fixed versions.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.clone-destination-dir</literal> - Where should the Spring Cloud Release repo get cloned to. If null defaults to a temporary directory.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.release-train-bom-url</literal> - URL to a project containing a BOM. Defaults to Spring Cloud Release Git repository: <literal><link xl:href="https://github.com/spring-cloud/spring-cloud-release">https://github.com/spring-cloud/spring-cloud-release</link></literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.documentation-url</literal> - URL to the documentation Git repository. Defaults to <literal><link xl:href="https://github.com/spring-cloud/spring-cloud-static">https://github.com/spring-cloud/spring-cloud-static</link></literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.documentation-branch</literal> - Branch to check out for the documentation project. Defaults to <literal>gh-pages</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.sagan.update-sagan</literal> - If <literal>true</literal> then will update project sagan with information about this project. Defaults to <literal>true</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.oauth-token</literal> - GitHub OAuth token to be used to interact with GitHub repo.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.username</literal> - Optional Git username. If not passed keys will be used for authentication.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.password</literal> - Optional Git password. If not passed keys will be used for authentication.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.git.number-of-checked-milestones</literal> - 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 <literal>10</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.maven.build-command</literal> - Command to be executed to build the project. Defaults to <literal>./mvnw clean install -Pdocs</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.maven.deploy-command</literal> - Command to be executed to deploy a built project". Defaults to <literal>./mvnw deploy -DskipTests -Pfast</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.maven.publish-docs-commands</literal> - Command to be executed to deploy a built project. If present <literal>{{version}}</literal> will be replaced by the proper version.
|
|
Defaults to the standard Spring Cloud wget and execution of ghpages.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.maven.system-properties</literal> - Additional system properties that should be passed to any commands. If present <literal>{{systemProps}}</literal> will be replaced by the contents of this property.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.maven.wait-time-in-minutes</literal> - Max wait time in minutes for the process to finish. Defaults to <literal>20</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.gradle.gradle-props-substitution</literal> - a map containing a <literal>key</literal> which is a property key inside <literal>gradle.properties</literal> and a <literal>value</literal> of
|
|
a project name. E.g. in <literal>gradle.properties</literal> you have <literal>foo=1.0.0.BUILD-SNAPSHOT</literal> and you would like <literal>spring-cloud-contract</literal> version to
|
|
be set there. Just provide a mapping for the <literal>gradle-props-substition</literal> looking like this <literal>foo=spring-cloud-contract</literal> and the result
|
|
(e.g for sc-contract version <literal>2.0.0.RELEASE</literal>) will be an updated <literal>gradle.properties</literal> with entry <literal>foo=2.0.0.RELEASE</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.pom.branch</literal> - Which branch of Spring Cloud Release should be checked out. Defaults to <literal>master</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.pom.pom-with-boot-starter-parent</literal> - What is the location of the <literal>pom.xml</literal> that contains the <literal>spring-boot-starter-parent</literal> as its parent pom. Defaults to <literal>spring-cloud-starter-parent/pom.xml</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.pom.this-train-bom</literal> - What is the location of the <literal>pom.xml</literal> that contains all the versions for the release train. Defaults to <literal>spring-cloud-dependencies/pom.xml</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.pom.bom-version-pattern</literal> - Regular expression that will match the versions of projects in the BOM pom.xml. Defaults to <literal>^(spring-cloud-.*)\.version$</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.pom.ignored-pom-regex</literal> - List of regular expressions of ignored poms. Defaults to test projects and samples.
|
|
Example: <literal>"--releaser.pom.ignored-pom-regex=".*\\.git/.*$,.{asterisk}spring-cloud-contract-maven-plugin/src/test/projects/.*$,.*spring-cloud-contract-maven-plugin/target/.*$,.*samples/standalone/[a-z]+/.*$"</literal>.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.working-dir</literal> - By default Releaser assumes running the program from the current working directory.</simpara>
|
|
</listitem>
|
|
<listitem>
|
|
<simpara><literal>releaser.template.template-folder</literal> - Tells which subfolder with templates to pick for blog, email etc. generation. Defaults to <literal>cloud</literal>.</simpara>
|
|
</listitem>
|
|
</itemizedlist>
|
|
<tip>
|
|
<simpara>You can pass the options either via system properties or via application arguments.
|
|
Example for system properties: <literal>java -Dreleaser.pom.branch=Camden.SR6 -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar</literal>
|
|
Example for application arguments: <literal>java -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar --releaser.pom.branch=Camden.SR6</literal></simpara>
|
|
</tip>
|
|
<important>
|
|
<simpara>For the GA release to be successful, it’s important that if the <literal>build</literal> / <literal>deploy</literal> command
|
|
run a script (e.g. <literal>scripts/foo.sh</literal>) then inside <literal>foo.sh</literal> if you call a Maven build <literal>./mvnw clean install</literal>
|
|
then <emphasis role="strong">remember to pass all arguments of the script there too</emphasis>. E.g. <literal>./mvnw clean install ${@}</literal>. That’s because
|
|
the releaser will pass any system properties to the <literal>build</literal> / <literal>deploy</literal> command, such as system properties
|
|
with keys and we need them to be passed inside the command executed by the releaser.</simpara>
|
|
</important>
|
|
</section>
|
|
<section xml:id="_examples">
|
|
<title>Examples</title>
|
|
<section xml:id="_keeping_configuration_in_the_project">
|
|
<title>Keeping configuration in the project</title>
|
|
<simpara>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. <literal>releaser.yml</literal> under <literal>config</literal>
|
|
folder and run your application like this:</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/spring-cloud-release-tools-spring/1.0.0.M1/spring-cloud-release-tools-spring-1.0.0.M1.jar -O ../spring-cloud-release-tools-spring-1.0.0.M1.jar
|
|
$ java -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar --spring.config.name=releaser</programlisting>
|
|
<tip>
|
|
<simpara>Notice that we’re downloading the jar to a parent folder, not to <literal>target</literal>. That’s because <literal>target</literal> get cleaned
|
|
during the build process</simpara>
|
|
</tip>
|
|
<important>
|
|
<simpara>For the meta-releaser to work we assume that the path to the
|
|
configuration file is always <literal>config/releaser.yml</literal>.</simpara>
|
|
</important>
|
|
</section>
|
|
<section xml:id="_specifying_a_branch">
|
|
<title>Specifying A Branch</title>
|
|
<simpara>By deafult the releaser will default to using the <literal>master</literal> branch of <literal>spring-cloud-release</literal>.
|
|
If you would like to use another branch you can specify it using the <literal>releaser.pom.branch</literal> property.</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ java -jar spring-cloud-release-tools-spring-1.0.0.M1.jar --releaser.pom.branch=Camden.SR6</programlisting>
|
|
</section>
|
|
<section xml:id="_using_environment_variables">
|
|
<title>Using Environment Variables</title>
|
|
<simpara>In some cases it might be easier to specify environment variables instead of passing parameters to
|
|
<literal>releaser</literal>. 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</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered">$ export RELEASER_POM_BRANCH=Dalston.RELEASE
|
|
$ export RELEASER_GIT_OAUTH_TOKEN=...
|
|
$ wget https://repo.spring.io/libs-milestone/org/springframework/cloud/internal/spring-cloud-release-tools-spring/1.0.0.M1/spring-cloud-release-tools-spring-1.0.0.M1.jar -O spring-cloud-release-tools-spring-1.0.0.M1.jar
|
|
$ java -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar --releaser.working-dir=/path/to/project/root</programlisting>
|
|
</section>
|
|
</section>
|
|
<section xml:id="_faq">
|
|
<title>FAQ</title>
|
|
<section xml:id="_jschexception_auth_fail">
|
|
<title>JSchException: Auth fail</title>
|
|
<simpara>I got such an exception</simpara>
|
|
<screen>Caused by: org.eclipse.jgit.errors.TransportException: git@github.com:spring-cloud/spring-cloud-sleuth.git: Auth fail
|
|
at org.eclipse.jgit.transport.JschConfigSessionFactory.getSession(JschConfigSessionFactory.java:160) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
at org.eclipse.jgit.transport.SshTransport.getSession(SshTransport.java:137) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
at org.eclipse.jgit.transport.TransportGitSsh$SshPushConnection.<init>(TransportGitSsh.java:322) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
at org.eclipse.jgit.transport.TransportGitSsh.openPush(TransportGitSsh.java:167) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
at org.eclipse.jgit.transport.PushProcess.execute(PushProcess.java:160) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
at org.eclipse.jgit.transport.Transport.push(Transport.java:1275) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
at org.eclipse.jgit.api.PushCommand.call(PushCommand.java:161) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
... 25 common frames omitted
|
|
Caused by: com.jcraft.jsch.JSchException: Auth fail
|
|
at com.jcraft.jsch.Session.connect(Session.java:512) ~[jsch-0.1.53.jar!/:na]
|
|
at org.eclipse.jgit.transport.JschConfigSessionFactory.getSession(JschConfigSessionFactory.java:117) ~[org.eclipse.jgit-4.6.0.201612231935-r.jar!/:4.6.0.201612231935-r]
|
|
... 31 common frames omitted</screen>
|
|
<simpara>To fix that just call</simpara>
|
|
<programlisting language="bash" linenumbering="unnumbered"># to run the agent
|
|
$ eval `ssh-agent`
|
|
# to store the pass in the agent
|
|
$ ssh-add ~/.ssh/id_rsa</programlisting>
|
|
<simpara>before running the app</simpara>
|
|
</section>
|
|
</section>
|
|
</chapter>
|
|
</book> |