-
Notifications
You must be signed in to change notification settings - Fork 1
/
using-git-flow.html
291 lines (236 loc) · 13.7 KB
/
using-git-flow.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
<!DOCTYPE html>
<!--
| Generated by Apache Maven Doxia Site Renderer 1.7.4 at 30 Jun 2023
| Rendered using Bloomreach Forge Maven Skin 3.2.1 based on Apache Maven Fluido Skin
-->
<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta charset="UTF-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<meta name="Date-Revision-yyyymmdd" content="20230630" />
<meta http-equiv="Content-Language" content="en" />
<title>Bloomreach Forge Documentation – Branching and releasing with git flow</title>
<link rel="stylesheet" href="./css/forge-maven-skin-syntaxhighlighter-3.2.1.min.css"/>
<link rel="stylesheet" href="./css/forge-maven-skin-3.2.1.min.css"/>
<link rel="stylesheet" href="./css/site.css" />
<link rel="stylesheet" href="./css/print.css" media="print" />
<link rel="icon" type="image/png" href="./images/skin/logo_64.png" sizes="64x64">
<script type="text/javascript" src="./js/forge-maven-skin-syntaxhighlighter-3.2.1.min.js"></script>
<script type="text/javascript" src="./js/forge-maven-skin-3.2.1.min.js"></script>
<style>.github-fork-ribbon:before { background-color: green; }</style>
</head>
<body class="topBarDisabled">
<a target="_blank" class="github-fork-ribbon right" href="https://github.com/bloomreach-forge/bloomreach-forge.github.io"
data-ribbon="Fork me on GitHub" title="Fork me on GitHub">Fork me on GitHub</a>
<div class="container-fluid">
<div id="banner">
<div id="logo">
<a href="https://bloomreach-forge.github.io">
<img src="./images/skin/logo.png" alt="Bloomreach Forge Logo" />
</a>
</div>
<div class="pull-left"> <div id="bannerLeft"> <h1>Bloomreach Forge Documentation</h1>
</div>
</div>
<div class="pull-right"></div>
<div class="clear"><hr/></div>
</div>
<div id="breadcrumbs">
<div class="links">
<a href="https://xmdocumentation.bloomreach.com">xmdocumentation.bloomreach.com</a>
<a href="https://github.com/bloomreach-forge">github.com/bloomreach-forge</a>
</div>
<ul class="breadcrumb">
<li id="publishDate">published: 30 Jun 2023
</li>
</ul>
<div class="clear"><hr/></div>
</div>
<div class="row-fluid">
<div id="leftColumn" class="span2">
<div class="well sidebar-nav">
<ul class="nav nav-list">
<li> <a href="index.html" title="Home"> <span class="none"></span> Home</a> </li>
<li> <a href="project-list.html" title="Project List"> <span class="none"></span> Project List</a> </li>
<li> <a href="development.html" title="Development"> <span class="none"></span> Development</a> </li>
<li class="active"> <a href="#"><span class="none"></span>Using Git Flow</a>
</li>
<li> <a href="checklist.html" title="Quality Checklist"> <span class="none"></span> Quality Checklist</a> </li>
</ul>
<hr />
<div id="poweredBy">
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<div class="clear"></div>
<a href="http://maven.apache.org/" title="Built by Maven" class="poweredBy"> <img class="builtBy" alt="Built by Maven" src="./images/logos/maven-feather.png" /> </a>
</div>
</div>
</div>
<div id="bodyColumn" class="span10" >
<div class="section">
<h2><a name="Branching_and_releasing_with_git_flow"></a>Branching and releasing with git flow</h2>
<p>We recommend to use git-flow as branching model in Bloomreach Forge projects because it is easier for most people to understand and follow and also widely accepted. This page explains how to set up <tt>git flow</tt> and how to release and deploy artifacts.</p>
<p>The instructions are based on these available references:</p>
<ul>
<li><a class="externalLink" href="http://danielkummer.github.io/git-flow-cheatsheet/">http://danielkummer.github.io/git-flow-cheatsheet/</a></li>
<li><a class="externalLink" href="https://gitversion.readthedocs.io/en/latest/git-branching-strategies/gitflow-examples/">https://gitversion.readthedocs.io/en/latest/git-branching-strategies/gitflow-examples/</a></li>
<li><a class="externalLink" href="http://nvie.com/posts/a-successful-git-branching-model/">http://nvie.com/posts/a-successful-git-branching-model/</a></li>
</ul>
<div class="section">
<h3><a name="Git_flow_set-up"></a>Git flow set-up</h3>
<p>In order to use <tt>git flow</tt> in your local workspace folder, do the following first, once:</p>
<ul>
<li>Have two branches, <tt>master</tt> and <tt>develop</tt>, in prior.</li>
<li>Initialize your working space once for the first time by running <tt>git flow init</tt> and accepting the default settings.</li>
<li>It is recommended to set the default branch to <tt>develop</tt>. Change the settings of the project to change the default branch to <tt>develop</tt>.</li>
</ul>
<p>After an initial release, the ‘master’ branch is always the same as the latest tag, whilst the ‘develop’ branch, and possibly ‘support/x.y’ branches, are used as base for features and bug fixes. </p></div>
<div class="section">
<h3><a name="Maintenance_support_branches"></a>Maintenance support branches</h3>
<p>If you want to have maintenance branches supporting older versions, you can use <tt>git flow support</tt> subcommand. You create it from a tag or a commit hash.</p>
<div class="source">
<div class="source"><pre>git flow support start x.y tag-x.y.z
</pre></div></div>
<p>The above creates a branch <tt>support/x.y</tt> from a tag called ‘tag-x.y.z’. So for instance, if develop is on 2.0.0-SNAPSHOT, and you want to create a support branch for the 1.x range, you can create a support/1.x branch from latest tag 1.5.0.</p>
<p>Git flow is only about branching so you must set the correct SNAPSHOT versions manually and commit, push it. </p></div>
<div class="section">
<h3><a name="How_to_release_with_git_flow_1_minute_version"></a>How to release with git flow, 1 minute version</h3>
<p>From develop (or from support/x.y) branch, create release x.y.z: </p>
<ol style="list-style-type: decimal">
<li>Start: <tt>git flow release start x.y.z develop</tt> (or from <tt>support/x.y</tt>)</li>
<li>Set release version: <tt>mvn versions:set -DnewVersion="x.y.z"</tt>, also for demo.</li>
<li>Commit: <tt>git commit -a -m "<ISSUE_ID> releasing x.y.z: set version"</tt></li>
<li>Finish: <tt>git flow release finish x.y.x</tt></li>
<li>Set next version: <tt>mvn versions:set -DnewVersion="x.y.z+1-SNAPSHOT"</tt>, also for demo.</li>
<li>Commit: <tt>git commit -a -m "<ISSUE_ID> releasing x.y.z: set next development version"</tt></li>
<li>Push: <tt>git push origin develop</tt> (or <tt>support/x.y</tt>)</li>
</ol>
<p>When started from <tt>develop</tt>, <tt>master</tt> is now same as the release. Then from master:</p>
<ol style="list-style-type: decimal">
<li>Regenerate docs: usually <tt>mvn clean site -Pgithub.pages</tt></li>
<li>Commit: <tt>git commit -a -m "<ISSUE_ID> releasing x.y.z: regenerate docs"</tt></li>
<li>Push: <tt>git push origin master</tt></li>
</ol>
<p>Push the tag & deploy artifacts:</p>
<ol style="list-style-type: decimal">
<li>Push: <tt>git push origin x.y.z</tt></li>
<li>Check out: <tt>git checkout tags/x.y.z</tt></li>
<li>Deploy artifacts: <tt>mvn deploy</tt></li>
</ol></div>
<div class="section">
<h3><a name="How_to_release_with_git_flow_detailed_version"></a>How to release with git flow, detailed version</h3>
<div class="section">
<div class="section">
<h5><a name="Start_a_new_release"></a>Start a new release</h5>
<p>With <tt>git flow release start</tt> a release branch is created. You can do that from <tt>develop</tt> branch (as in the this example) but also from <tt>support/x.y</tt> branch.</p>
<div class="source">
<div class="source"><pre> git flow release start x.y.z develop
</pre></div></div>
<p>Now, you’re automatically moved to a new branch already, <tt>release/x.y.z</tt>.</p></div>
<div class="section">
<h5><a name="Set_release_versions"></a>Set release versions</h5>
<p>It’s time to set a proper release version in the pom.xml files. For example,</p>
<div class="source">
<div class="source"><pre> mvn versions:set -DgenerateBackupPoms=false -DnewVersion="x.y.z"
</pre></div></div>
<p>Also, if you have <tt>demo</tt> folder underneath, set the release version in the demo folder as well:</p>
<div class="source">
<div class="source"><pre> cd demo
mvn versions:set -DgenerateBackupPoms=false -DnewVersion="x.y.z"
cd ..
</pre></div></div>
<p><b>NOTE</b>: <tt>demo</tt> is a child folder managed in the same git repository, but not a maven submodule. That’s why you set the maven versions separately.</p>
<p>Let’s commit the version changes. For example,</p>
<div class="source">
<div class="source"><pre> git commit -a -m "<ISSUE_ID> releasing x.y.z: set version"
</pre></div></div></div>
<div class="section">
<h5><a name="aOptionally_publish_the_release_branch"></a>(Optionally) publish the release branch</h5>
<p>You can skip this step if you are releasing it alone, but if you want your team to do final hardening in the shared release branch, you should do this step.</p>
<div class="source">
<div class="source"><pre> git flow release publish x.y.z
</pre></div></div>
<p>Now, your release branch was published. You can inform the team of this new release branch for final hardening work.</p></div>
<div class="section">
<h5><a name="Finish_the_release"></a>Finish the release</h5>
<p>Finally, let’s finish the release. This step includes making a tag, merging changes to master and develop branches and removing the release branch.</p>
<div class="source">
<div class="source"><pre> git flow release finish x.y.z
</pre></div></div>
<p>This finishing step removes the <tt>release/x.y.z</tt> branch <i>locally</i>, and moves to <tt>develop</tt> branch.</p></div>
<div class="section">
<h5><a name="Bump_version_in_develop_branch_and_push_it."></a>Bump version in develop branch and push it.</h5>
<p>In the finishing step above, every change was already merged to <tt>master</tt> and <tt>develop</tt> branch from the release branch. So, don’t forget to push local commits to the remote.</p>
<p>Before pushing the commits in <tt>develop</tt> branch, let’s bump the version for next development cycle with <tt>-SNAPSHOT</tt> in <tt>develop</tt> branch.</p>
<div class="source">
<div class="source"><pre> mvn versions:set -DgenerateBackupPoms=false -DnewVersion="x.y.z+1-SNAPSHOT"
</pre></div></div>
<p>Again, don’t forget bumping up versions in the demo folder if it exists.</p>
<div class="source">
<div class="source"><pre> cd demo
mvn versions:set -DgenerateBackupPoms=false -DnewVersion="x.y.z+1-SNAPSHOT"
cd ..
git commit -a -m "<ISSUE_ID> releasing x.y.z: set next development version"
git push origin develop
</pre></div></div></div>
<div class="section">
<h5><a name="Push_master_branch."></a>Push master branch.</h5>
<p>If the release was done from develop branch, not from support branch, <tt>master</tt> should be the same as the release branch. Next is to generate docs (if applicable) and commit, push.</p>
<div class="source">
<div class="source"><pre> git checkout master
mvn clean site -Pgithub.pages
git commit -a -m "<ISSUE_ID> releasing x.y.z: regenerate docs"```
git push origin master
</pre></div></div></div>
<div class="section">
<h5><a name="Push_the_newly_created_tag."></a>Push the newly created tag.</h5>
<p>In the finishing step, a tag was made for the release version. e.g, <tt>x.y.z</tt></p>
<p>You can check all the tags by the following command:</p>
<div class="source">
<div class="source"><pre> git tag -l
</pre></div></div>
<p><b>Tip</b>: You can also run the following command to fetch all the tags pushed by someone else in the remote:</p>
<div class="source">
<div class="source"><pre> git fetch --all --tags --prune
</pre></div></div>
<p>Now, let’s push the newly created tag generated in the finishing step:</p>
<div class="source">
<div class="source"><pre> git push origin x.y.z
</pre></div></div>
<p>If you’ve published the release branch in the previous optional step, you may now remove the remote (temporary) release branch:</p>
<div class="source">
<div class="source"><pre> git push origin --delete release/x.y.z
</pre></div></div>
<p>Now, your normal release process is done. Your new release was made as a tag and published.</p></div>
<div class="section">
<h5><a name="Deploy_the_release_tag_to_Bloomreach_Forge_Maven_Repository"></a>Deploy the release tag to Bloomreach Forge Maven Repository</h5>
<p>Check out the release tag like the following example. You may name the local branch to anything else.</p>
<div class="source">
<div class="source"><pre> git checkout tags/x.y.z -b tag-x.y.z
</pre></div></div>
<p>Now, deploy it to Bloomreach Forge Maven repository from the tag branch:</p>
<div class="source">
<div class="source"><pre> mvn deploy
</pre></div></div>
<p>You may remove the local tag branch.</p>
<div class="source">
<div class="source"><pre> git checkout develop
git branch -D tag-x.y.z
</pre></div></div>
<p>Congratulations! Great work!</p></div></div></div></div>
</div>
</div>
</div>
<hr/>
<footer>
<div class="container-fluid">
<div class="row-fluid">
<p class="copyright">Copyright © 2017–2023.
<a href="https://www.bloomreach.com">Bloomreach Inc.</a>.
</p>
</div>
</div>
</footer>
</body>
</html>