SpringCloud/spring-cloud-release-tools
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Sync docs from master to gh-pages

Browse Source
This commit is contained in:
Marcin Grzejszczak
2017-08-31 13:53:05 +02:00
parent 99020db338
commit 4c58504e7e
88 changed files with 5856 additions and 730 deletions
Download Patch File Download Diff File Expand all files Collapse all files

59
single/spring-cloud-release-tools.html Normal file
View File

@@ -0,0 +1,59 @@
<html><head>
<meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
<title>Spring Cloud Release Tools</title><link rel="stylesheet" type="text/css" href="css/manual-singlepage.css"><meta name="generator" content="DocBook XSL Stylesheets V1.78.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div lang="en" class="book"><div class="titlepage"><div><div><h1 class="title"><a name="d0e3"></a>Spring Cloud Release Tools</h1></div></div><hr></div><div class="toc"><p><b>Table of Contents</b></p><dl class="toc"><dt><span class="chapter"><a href="#_spring_cloud_release_tools">1. Spring Cloud Release Tools</a></span></dt><dd><dl><dt><span class="section"><a href="#_what_does_it_do">1.1. What does it do?</a></span></dt><dt><span class="section"><a href="#_how_to_run_it">1.2. How to run it</a></span></dt><dt><span class="section"><a href="#_project_options">1.3. Project options</a></span></dt><dt><span class="section"><a href="#_examples">1.4. Examples</a></span></dt><dd><dl><dt><span class="section"><a href="#_keeping_configuration_in_the_project">1.4.1. Keeping configuration in the project</a></span></dt><dt><span class="section"><a href="#_specifying_a_branch">1.4.2. Specifying A Branch</a></span></dt><dt><span class="section"><a href="#_using_environment_variables">1.4.3. Using Environment Variables</a></span></dt></dl></dd><dt><span class="section"><a href="#_faq">1.5. FAQ</a></span></dt><dd><dl><dt><span class="section"><a href="#_jschexception_auth_fail">1.5.1. JSchException: Auth fail</a></span></dt></dl></dd></dl></dd></dl></div><div class="chapter"><div class="titlepage"><div><div><h1 class="title"><a name="_spring_cloud_release_tools" href="#_spring_cloud_release_tools"></a>1.&nbsp;Spring Cloud Release Tools</h1></div></div></div><p>Spring Cloud projects reuse the same pattern of building and deploying the applications. That&#8217;s
why this tool makes it easy to automate the release / dependency update process of our applications.</p><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_what_does_it_do" href="#_what_does_it_do"></a>1.1&nbsp;What does it do?</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem">Clones the Spring Cloud Release project and picks all versions (Boot + Cloud projects)</li><li class="listitem"><p class="simpara">Modifies the project versions with values from SC-Release</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">throws an exception when we bump versions to release and there&#8217;s a SNAPSHOT version referenced in the POM</li></ul></div></li><li class="listitem"><p class="simpara">Performs the build and checks if the <code class="literal">docs</code> modules have properly created the documentation</p><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: circle; "><li class="listitem">throws an exception when in the <code class="literal">docs</code> module there&#8217;s an unresolved tag in any HTML file</li></ul></div></li><li class="listitem">Commits changed poms (ONLY FOR NON-SNAPSHOT VERSIONS)</li><li class="listitem">Creates a tag for the release / milestone (ONLY FOR NON-SNAPSHOT VERSIONS)</li><li class="listitem">Runs the deployment of the artifacts</li><li class="listitem">Publishes the docs (to <code class="literal">spring-cloud-static</code> for non-snapshots, to <code class="literal">gh-pages</code> for snapshots)</li><li class="listitem">Reverts back to snapshots, bumps the version by a patch (<code class="literal">1.0.1.RELEASE</code> &#8594; <code class="literal">1.0.2.BUILD-SNAPSHOT</code>) (ONLY FOR RELEASE VERSIONS)</li><li class="listitem">Closes the milestone on Github (e.g. <code class="literal">v1.0.1.RELEASE</code>) (ONLY FOR NON-SNAPSHOT VERSIONS)</li><li class="listitem">Generates an email template under <code class="literal">target/email.txt</code> (ONLY FOR NON-SNAPSHOT VERSIONS)</li><li class="listitem">Generates a blog template under <code class="literal">target/blog.md</code> (ONLY FOR NON-SNAPSHOT VERSIONS)</li><li class="listitem">Generates a tweet template under <code class="literal">target/tweet.txt</code> (ONLY FOR NON-SNAPSHOT VERSIONS)</li></ul></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_how_to_run_it" href="#_how_to_run_it"></a>1.2&nbsp;How to run it</h2></div></div></div><p>Members of the Spring Cloud Team typically use this tool as follows. They first
clone the releaser locally and build the jar manually</p><pre class="programlisting">$ git clone git@github.com:spring-cloud/spring-cloud-release-tools.git
$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">cd</span> spring-cloud-release-tools
$ ./mvnw clean install</pre><p>Go to your project (e.g. Spring Cloud Sleuth)</p><pre class="programlisting">$ git clone git@github.com:spring-cloud/spring-cloud-sleuth.git
$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">cd</span> spring-cloud-sleuth
$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># example of running the releaser agains Dalston.SR1 tag with 1.0.0.BUILD-SNAPSHOT version of the releaser</span>
$ java -jar ~/repo/spring-cloud-release-tools/spring-cloud-release-tools-spring/target/spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>BUILD-SNAPSHOT.jar --releaser.pom.branch=vDalston.SR1 --spring.config.name=releaser</pre><p>The application will start running from your working directory.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>It is important that you clone the repository you are going to release using SSH in order for the
<code class="literal">releaser</code> to be able to push tags and commit changes automatically.</p></td></tr></table></div><p>You will see text similar to this one</p><pre class="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 to Artifactory
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 / tweet etc. templates
You can press 'q' to quit</pre><p>Just pick a number and continue! Pick either a full release or single steps.</p><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Read before picking a number cause it might have changed between tool releases ;)</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_project_options" href="#_project_options"></a>1.3&nbsp;Project options</h2></div></div></div><div class="itemizedlist"><ul class="itemizedlist" style="list-style-type: disc; "><li class="listitem"><code class="literal">releaser.fixed-versions</code> - A String to String mapping of manually set versions. E.g. <code class="literal">"spring-cloud-cli" &#8594; "1.0.0.RELEASE"</code> will set
the <code class="literal">spring-cloud-cli.version</code> to <code class="literal">1.0.0.RELEASE</code> regardless of what was set in <code class="literal">spring-cloud-release</code> project</li><li class="listitem"><code class="literal">releaser.git.clone-destination-dir</code> - Where should the Spring Cloud Release repo get cloned to. If null defaults to a temporary directory</li><li class="listitem"><code class="literal">releaser.git.spring-cloud-release-git-url</code> - URL to Spring Cloud Release Git repository. Defaults to <code class="literal"><a class="link" href="https://github.com/spring-cloud/spring-cloud-release" target="_top">https://github.com/spring-cloud/spring-cloud-release</a></code></li><li class="listitem"><code class="literal">releaser.git.oauth-token</code> - GitHub OAuth token to be used to interact with GitHub repo.</li><li class="listitem"><code class="literal">releaser.maven.build-command</code> - Command to be executed to build the project. Defaults to <code class="literal">./mvnw clean install -Pdocs</code></li><li class="listitem"><code class="literal">releaser.maven.deploy-command</code> - Command to be executed to deploy a built project". Defaults to <code class="literal">./mvnw deploy -DskipTests -Pfast</code></li><li class="listitem"><code class="literal">releaser.maven.publish-docs-commands</code> - Command to be executed to deploy a built project. If present <code class="literal">{{version}}</code> will be replaced by the proper version.
Defaults to the standard Spring Cloud wget and execution of ghpages.</li><li class="listitem"><code class="literal">releaser.maven.wait-time-in-minutes</code> - Max wait time in minutes for the process to finish. Defaults to <code class="literal">20</code></li><li class="listitem"><code class="literal">releaser.gradle.gradle-props-substitution</code> - a map containing a <code class="literal">key</code> which is a property key inside <code class="literal">gradle.properties</code> and a <code class="literal">value</code> of
a project name. E.g. in <code class="literal">gradle.properties</code> you have <code class="literal">foo=1.0.0.BUILD-SNAPSHOT</code> and you would like <code class="literal">spring-cloud-contract</code> version to
be set there. Just provide a mapping for the <code class="literal">gradle-props-substition</code> looking like this <code class="literal">foo=spring-cloud-contract</code> and the result
(e.g for sc-contract version <code class="literal">2.0.0.RELEASE</code>) will be an updated <code class="literal">gradle.properties</code> with entry <code class="literal">foo=2.0.0.RELEASE</code></li><li class="listitem"><code class="literal">releaser.pom.branch</code> - Which branch of Spring Cloud Release should be checked out. Defaults to "master",</li><li class="listitem"><code class="literal">releaser.pom.ignored-pom-regex</code> - List of regular expressions of ignored poms. Defaults to test projects and samples.,</li><li class="listitem"><code class="literal">releaser.working-dir</code> - By default Releaser assumes running the program from the current working directory.</li></ul></div><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>You can pass the options either via system properties or via application arguments.
Example for system properties: <code class="literal">java -Dreleaser.pom.branch=Camden.SR6 -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar</code>
Example for application argumemts: <code class="literal">java -jar target/spring-cloud-release-tools-spring-1.0.0.M1.jar --releaser.pom.branch=Camden.SR6</code></p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_examples" href="#_examples"></a>1.4&nbsp;Examples</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_keeping_configuration_in_the_project" href="#_keeping_configuration_in_the_project"></a>1.4.1&nbsp;Keeping configuration in the project</h3></div></div></div><p>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. <code class="literal">releaser.yml</code> under <code class="literal">config</code>
folder and run your application like this:</p><pre class="programlisting">$ wget http://repo.spring.io/libs-milestone/org/springframework/cloud/internal/spring-cloud-release-tools-spring/<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1/spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1.jar -O ../spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1.jar
$ java -jar target/spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1.jar --spring.config.name=releaser</pre><div class="tip" style="margin-left: 0.5in; margin-right: 0.5in;"><table border="0" summary="Tip"><tr><td rowspan="2" align="center" valign="top" width="25"><img alt="[Tip]" src="images/tip.png"></td><th align="left">Tip</th></tr><tr><td align="left" valign="top"><p>Notice that we&#8217;re downloading the jar to a parent folder, not to <code class="literal">target</code>. That&#8217;s because <code class="literal">target</code> get cleaned
during the build process</p></td></tr></table></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_specifying_a_branch" href="#_specifying_a_branch"></a>1.4.2&nbsp;Specifying A Branch</h3></div></div></div><p>By deafult the releaser will default to using the <code class="literal">master</code> branch of <code class="literal">spring-cloud-release</code>.
If you would like to use another branch you can specify it using the <code class="literal">releaser.pom.branch</code> property.</p><pre class="programlisting">$ java -jar spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1.jar --releaser.pom.branch=Camden.SR6</pre></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_using_environment_variables" href="#_using_environment_variables"></a>1.4.3&nbsp;Using Environment Variables</h3></div></div></div><p>In some cases it might be easier to specify environment variables instead of passing parameters to
<code class="literal">releaser</code>. 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</p><pre class="programlisting">$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">export</span> RELEASER_POM_BRANCH=Dalston.RELEASE
$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">export</span> RELEASER_GIT_OAUTH_TOKEN=...
$ wget http://repo.spring.io/libs-milestone/org/springframework/cloud/internal/spring-cloud-release-tools-spring/<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1/spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1.jar -O spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1.jar
$ java -jar target/spring-cloud-release-tools-spring-<span class="hl-number">1.0</span>.<span class="hl-number">0.</span>M1.jar --releaser.working-dir=/path/to/project/root</pre></div></div><div class="section"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="_faq" href="#_faq"></a>1.5&nbsp;FAQ</h2></div></div></div><div class="section"><div class="titlepage"><div><div><h3 class="title"><a name="_jschexception_auth_fail" href="#_jschexception_auth_fail"></a>1.5.1&nbsp;JSchException: Auth fail</h3></div></div></div><p>I got such an exception</p><pre class="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.&lt;init&gt;(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</pre><p>To fix that just call</p><pre class="programlisting"><span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># to run the agent</span>
$ <span xmlns:d="http://docbook.org/ns/docbook" class="hl-keyword">eval</span> `ssh-agent`
<span xmlns:d="http://docbook.org/ns/docbook" class="hl-comment"># to store the pass in the agent</span>
$ ssh-add ~/.ssh/id_rsa</pre><p>before running the app</p></div></div></div></div></body></html>