-
Notifications
You must be signed in to change notification settings - Fork 0
/
GitWorkflow.html
327 lines (284 loc) · 21.5 KB
/
GitWorkflow.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
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
<!DOCTYPE html>
<html lang="en" data-content_root="./">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="viewport" content="width=device-width, initial-scale=1" />
<title>Mantid Git Workflow</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=fa44fd50" />
<link rel="stylesheet" type="text/css" href="_static/bootstrap-sphinx.css?v=fadd4351" />
<link rel="stylesheet" type="text/css" href="_static/custom.css?v=77160d70" />
<script src="_static/documentation_options.js?v=a8da1a53"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="The Automated Build Process" href="AutomatedBuildProcess.html" />
<link rel="prev" title="Mantid Git Config" href="GitConfig.html" />
<script>
(function(i,s,o,g,r,a,m){i['GoogleAnalyticsObject']=r;i[r]=i[r]||function(){
(i[r].q=i[r].q||[]).push(arguments)},i[r].l=1*new Date();a=s.createElement(o),
m=s.getElementsByTagName(o)[0];a.async=1;a.src=g;m.parentNode.insertBefore(a,m)
})(window,document,'script','//www.google-analytics.com/analytics.js','ga');
ga('create', 'UA-59110517-1', 'auto');
ga('send', 'pageview');
</script>
</head><body>
<div id="navbar" class="navbar navbar-default ">
<div class="container">
<div class="navbar-header">
<!-- .btn-navbar is used as the toggle for collapsed navbar content -->
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".nav-collapse">
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="http://www.mantidproject.org">
</a>
<span class="navbar-text navbar-version pull-left"><b>main</b></span>
</div>
<div class="collapse navbar-collapse nav-collapse">
<ul class="nav navbar-nav">
<li class="divider-vertical"></li>
<li><a href="index.html">Home</a></li>
<li><a href="https://download.mantidproject.org">Download</a></li>
<li><a href="https://docs.mantidproject.org">User Documentation</a></li>
<li><a href="http://www.mantidproject.org/contact">Contact Us</a></li>
</ul>
<form class="navbar-form navbar-right" action="search.html" method="get">
<div class="form-group">
<input type="text" name="q" class="form-control" placeholder="Search" />
</div>
<input type="hidden" name="check_keywords" value="yes" />
<input type="hidden" name="area" value="default" />
</form>
</div>
</div>
<p>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="nav-item nav-item-0"><a href="index.html">Documentation</a> »</li>
<li class="nav-item nav-item-this"><a href="">Mantid Git Workflow</a></li>
</ul>
</div> </p>
</div>
<div class="container">
<div class="row">
<div class="body col-md-12 content" role="main">
<section id="mantid-git-workflow">
<span id="gitworkflow"></span><h1>Mantid Git Workflow<a class="headerlink" href="#mantid-git-workflow" title="Link to this heading">¶</a></h1>
<nav class="contents local" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#summary" id="id2">Summary</a></p></li>
<li><p><a class="reference internal" href="#description" id="id3">Description</a></p></li>
<li><p><a class="reference internal" href="#naming-branches" id="id4">Naming Branches</a></p></li>
<li><p><a class="reference internal" href="#pull-requests" id="id5">Pull Requests</a></p>
<ul>
<li><p><a class="reference internal" href="#checkout-a-pull-request" id="id6">Checkout a Pull Request</a></p></li>
<li><p><a class="reference internal" href="#stale-pull-requests" id="id7">Stale Pull Requests</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#code-freeze" id="id8">Code Freeze</a></p>
<ul>
<li><p><a class="reference internal" href="#new-branches" id="id9">New Branches</a></p></li>
<li><p><a class="reference internal" href="#id1" id="id10">Pull Requests</a></p></li>
<li><p><a class="reference internal" href="#fixing-a-pr-with-an-incorrect-base-branch" id="id11">Fixing a PR with an Incorrect Base Branch</a></p></li>
<li><p><a class="reference internal" href="#fixing-a-merge-conflict-between-protected-branches" id="id12">Fixing a merge conflict between protected branches</a></p></li>
</ul>
</li>
</ul>
</nav>
<section id="summary">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Summary</a><a class="headerlink" href="#summary" title="Link to this heading">¶</a></h2>
<p>Go to the <a class="reference internal" href="GitConfig.html"><span class="doc">Mantid Git Config</span></a> page to ensure that Git is set up correctly
before starting.</p>
<p>This page describes the workflow used in conjunction with <a class="reference external" href="http://git-scm.com">Git</a> and <a class="reference external" href="https://www.github.com/">GitHub</a> for
those who have push access to the repository.</p>
<p>Go <a class="reference external" href="https://education.github.com/git-cheat-sheet-education.pdf">here</a>
or <a class="reference external" href="https://www.atlassian.com/git/tutorials/atlassian-git-cheatsheet">here</a>
for a cheatsheet of Git commands.</p>
<p>Go <a class="reference external" href="https://github.com/k88hudson/git-flight-rules">here</a> for a
(fairly) comprehensive guide to solving your various Git problems.</p>
</section>
<section id="description">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Description</a><a class="headerlink" href="#description" title="Link to this heading">¶</a></h2>
<p>We follow the <a class="reference external" href="https://guides.github.com/introduction/flow/index.html">GitHub flow</a>, using
branches for new work and pull requests for verifying the work.</p>
<p>The steps for a new piece of work can be summarised as follows:</p>
<ol class="arabic simple">
<li><p>Push up or <a class="reference external" href="https://guides.github.com/features/issues">create</a> an
issue <a class="reference external" href="https://github.com/mantidproject/mantid/issues">here</a></p></li>
<li><p>Create a branch from <code class="docutils literal notranslate"><span class="pre">main</span></code> using the naming convention described
at <a class="reference internal" href="#gitworkflownamingbranches"><span class="std std-ref">Naming Branches</span></a></p></li>
<li><p>Do the work and commit changes to the branch. On commit, the
<a class="reference external" href="https://pre-commit.com/">pre-commit</a> framework will run, it will
check all your changes for formatting, linting, and perform static
analysis. Push the branch regularly to GitHub to make sure no work
is accidentally lost.</p></li>
<li><p>When you are finished with the work, ensure that all of the unit
tests, documentation tests and system tests if necessary pass on
your own machine</p></li>
<li><p>Open a pull request (<a class="reference internal" href="#gitworkflowpullrequests"><span class="std std-ref">Pull Requests</span></a>)
from the <a class="reference external" href="https://github.com/mantidproject/mantid/branches/">GitHub branches</a> page</p>
<ul class="simple">
<li><p>This will check with the buildservers for cross-platform
compatibility</p></li>
<li><p>If any issues come up, continue working on your branch and push
to GitHub - the pull request will update automatically</p></li>
</ul>
</li>
</ol>
</section>
<section id="naming-branches">
<span id="gitworkflownamingbranches"></span><h2><a class="toc-backref" href="#id4" role="doc-backlink">Naming Branches</a><a class="headerlink" href="#naming-branches" title="Link to this heading">¶</a></h2>
<p>When naming <a class="reference external" href="http://github.com/mantidproject/mantid/branches">public branches</a> that will be
pushed to GitHub, please follow the convention of
<code class="docutils literal notranslate"><span class="pre">issuenumber_short_description</span></code>. This will allow others to discover
what the branch is for (issue number) and quickly know what is being
done there (short description).</p>
</section>
<section id="pull-requests">
<span id="gitworkflowpullrequests"></span><h2><a class="toc-backref" href="#id5" role="doc-backlink">Pull Requests</a><a class="headerlink" href="#pull-requests" title="Link to this heading">¶</a></h2>
<p>For an general overview of using pull requests on GitHub look <a class="reference external" href="https://help.github.com/articles/using-pull-requests/">here</a>.</p>
<p>When creating a pull request you should:</p>
<ul class="simple">
<li><p>Ensure that the title succinctly describes the changes so it is easy
to read on the overview page</p>
<ul>
<li><p>The title should <strong>not</strong> contain the issue number</p></li>
</ul>
</li>
<li><p><a class="reference external" href="https://github.com/blog/1506-closing-issues-via-pull-requests">Reference the issue which the pull request is closing</a>, using one of <a class="reference external" href="https://help.github.com/articles/closing-issues-via-commit-messages">these</a> keywords</p></li>
<li><p>State the user and facility (if relevant) who initiated the original issue, if they are named in the issue. Please do not put full email addresses on the Pull Request, as it is publicly accessible.
If the user would not be easily identified by someone picking up the ticket, be prepared to act as a point of contact with the reporter.</p></li>
<li><p>Ensure the description follows the format described by the <a class="reference external" href="https://github.com/mantidproject/mantid/blob/main/.github/PULL_REQUEST_TEMPLATE.md">PR
template</a>
on GitHub</p></li>
</ul>
<p>A good example is <a class="reference external" href="https://github.com/mantidproject/mantid/pull/18713">here</a>.</p>
<p>Recommended reading: <a class="reference external" href="https://github.com/blog/1943-how-to-write-the-perfect-pull-request">How to Write the Perfect Pull Request</a></p>
<p>For further information about the review process see <a class="reference internal" href="ReviewingAPullRequest.html#reviewingapullrequest"><span class="std std-ref">reviewing a pull request</span></a>.</p>
<section id="checkout-a-pull-request">
<h3><a class="toc-backref" href="#id6" role="doc-backlink">Checkout a Pull Request</a><a class="headerlink" href="#checkout-a-pull-request" title="Link to this heading">¶</a></h3>
<p>To check out a particular pull request for functional testing use the <code class="docutils literal notranslate"><span class="pre">test-pr</span></code> alias that was set up in the <a class="reference internal" href="GitConfig.html"><span class="doc">Mantid Git Config</span></a> instructions.</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>test-pr<span class="w"> </span><remote-name><span class="w"> </span><ID>
</pre></div>
</div>
<p>where <code class="docutils literal notranslate"><span class="pre"><ID></span></code> is the pull request number given on GitHub and <code class="docutils literal notranslate"><span class="pre"><remote-name></span></code> is the name
of the remote pointing to the original <code class="docutils literal notranslate"><span class="pre">mantid</span></code> repository. If you cloned directly from <a class="reference external" href="https://github.com/mantidproject/mantid">mantid</a>
then <code class="docutils literal notranslate"><span class="pre">remote-name=origin</span></code> else if you cloned from a fork then it is the name of remote that points
back to the original repository.</p>
<p>Note that these commands will checkout a temporary branch that has the development branch merged with <code class="docutils literal notranslate"><span class="pre">main</span></code> and not just
the development branch on its own.</p>
<p>The <a class="reference internal" href="GitConfig.html"><span class="doc">Mantid Git Config</span></a> page also provides the follow alias to delete all <code class="docutils literal notranslate"><span class="pre">pr/</span></code> prefixed branches, which is useful if you have several:</p>
<div class="highlight-sh notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>test-pr-remove-all
</pre></div>
</div>
</section>
<section id="stale-pull-requests">
<h3><a class="toc-backref" href="#id7" role="doc-backlink">Stale Pull Requests</a><a class="headerlink" href="#stale-pull-requests" title="Link to this heading">¶</a></h3>
<p>Pull requests that go an extended period of time without any activity
are considered stale and will be picked up by a (partially) automated
bot which will notify those that are required to take action in order
to keep the review process going.</p>
<p>This is also used to notify developers of pull requests that develop
conflicts with the base branch and that fail continuous integration
tests, in those two cases the age of the pull request is ignored.</p>
<p>The reasons a pull request may be flagged up currently are:</p>
<ul class="simple">
<li><p>Conflicts with base branch</p></li>
<li><p>Failing CI</p></li>
<li><p>Last developer has left the Mantid team</p></li>
<li><p>Nobody has reviewed the PR</p></li>
<li><p>An assigned reviewer has yet to complete a review</p></li>
<li><p>A gatekeeper has not second reviewed an approved PR</p></li>
<li><p>A review from a specific user was requested but that user has yet to complete a review</p></li>
<li><p>The developer has yet to act on comments left in a review</p></li>
</ul>
<p>(code for the bot is currently <a class="reference external" href="https://github.com/DanNixon/mantid_pr_bot">here</a>)</p>
</section>
</section>
<section id="code-freeze">
<h2><a class="toc-backref" href="#id8" role="doc-backlink">Code Freeze</a><a class="headerlink" href="#code-freeze" title="Link to this heading">¶</a></h2>
<p>At the start of a <em>code freeze</em> before a major release there will be a
release branch created named <code class="docutils literal notranslate"><span class="pre">release-next</span></code>. At this point
only bugfixes should be applied to this release branch so that it can
be stabilized for the release. The release branch will be merged to
<code class="docutils literal notranslate"><span class="pre">main</span></code> periodically so bugfixes do not need to be separately
merged to <code class="docutils literal notranslate"><span class="pre">main</span></code>.</p>
<section id="new-branches">
<h3><a class="toc-backref" href="#id9" role="doc-backlink">New Branches</a><a class="headerlink" href="#new-branches" title="Link to this heading">¶</a></h3>
<p>During the code freeze it is important to ensure that a new branch is
created from the correct base branch depending on the scope of the
changes:</p>
<ul class="simple">
<li><p><code class="docutils literal notranslate"><span class="pre">main</span></code>: maintenance fixes, new features. Command: <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">fetch</span> <span class="pre">-p</span> <span class="pre">&&</span> <span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">--no-track</span> <span class="pre">-b</span> <span class="pre">MYBRANCH_NAME</span> <span class="pre">origin/main</span></code></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">release-next</span></code>: bugfixes. Command: <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">fetch</span> <span class="pre">-p</span> <span class="pre">&&</span> <span class="pre">git</span> <span class="pre">checkout</span> <span class="pre">--no-track</span> <span class="pre">-b</span> <span class="pre">MYBRANCH_NAME</span> <span class="pre">origin/release-next</span></code></p></li>
</ul>
</section>
<section id="id1">
<h3><a class="toc-backref" href="#id10" role="doc-backlink">Pull Requests</a><a class="headerlink" href="#id1" title="Link to this heading">¶</a></h3>
<p>To merge code with the release branch, open a pull request as usual but instead of using the
default merge target select <code class="docutils literal notranslate"><span class="pre">release-next</span></code>:</p>
<img alt="_images/release-branch-new-pr.png" src="_images/release-branch-new-pr.png" />
</section>
<section id="fixing-a-pr-with-an-incorrect-base-branch">
<h3><a class="toc-backref" href="#id11" role="doc-backlink">Fixing a PR with an Incorrect Base Branch</a><a class="headerlink" href="#fixing-a-pr-with-an-incorrect-base-branch" title="Link to this heading">¶</a></h3>
<p>The target branch on GitHub needs to match the base branch used in the
commands above when the branch was initially created. If the compare
view shows changes other than your own it is most likely that the base
branch is incorrect and it needs to be fixed.</p>
<p>As an example consider the scenario where a branch named <code class="docutils literal notranslate"><span class="pre">topic</span></code> has
been based off the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch as follows:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span> <span class="n">main</span>
<span class="o">|</span> \
<span class="o">|</span> <span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span> <span class="n">topic</span>
\
<span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span> <span class="n">release</span><span class="o">-</span><span class="nb">next</span>
</pre></div>
</div>
<p>where we actually want the <code class="docutils literal notranslate"><span class="pre">topic</span></code> branch based off <code class="docutils literal notranslate"><span class="pre">release-next</span></code>
instead i.e.</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span> <span class="n">main</span>
\
<span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span><span class="o">---</span><span class="n">o</span> <span class="n">release</span><span class="o">-</span><span class="nb">next</span>
\
<span class="n">o</span><span class="s1">'---o'</span><span class="o">---</span><span class="n">o</span><span class="s1">' topic</span>
</pre></div>
</div>
<p>To fix this situation we use the <code class="docutils literal notranslate"><span class="pre">rebase</span></code> command, providing the
<code class="docutils literal notranslate"><span class="pre">--onto</span></code> option as follows:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>fetch
git<span class="w"> </span>rebase<span class="w"> </span>--onto<span class="w"> </span>origin/release-next<span class="w"> </span><span class="k">$(</span>git<span class="w"> </span>merge-base<span class="w"> </span>origin/main<span class="w"> </span>origin/topic<span class="k">)</span><span class="w"> </span>topic
</pre></div>
</div>
</section>
<section id="fixing-a-merge-conflict-between-protected-branches">
<h3><a class="toc-backref" href="#id12" role="doc-backlink">Fixing a merge conflict between protected branches</a><a class="headerlink" href="#fixing-a-merge-conflict-between-protected-branches" title="Link to this heading">¶</a></h3>
<p>A Gatekeeper should follow <a class="reference internal" href="Gatekeeping.html#fixprotectedbranchmergeconflict"><span class="std std-ref">these instructions</span></a> if there is a merge conflict between two protected branches e.g. <code class="docutils literal notranslate"><span class="pre">main</span></code> and <code class="docutils literal notranslate"><span class="pre">release-next</span></code>.</p>
</section>
</section>
</section>
</div>
</div>
</div>
<footer class="footer">
<div class="container">
<ul class="nav navbar-nav" style=" float: right;">
<li>
<a href="GitConfig.html" title="Previous Chapter: Mantid Git Config"><span class="glyphicon glyphicon-chevron-left visible-sm"></span><span class="hidden-sm hidden-tablet">« Mantid Git Config</span>
</a>
</li>
<li>
<a href="AutomatedBuildProcess.html" title="Next Chapter: The Automated Build Process"><span class="glyphicon glyphicon-chevron-right visible-sm"></span><span class="hidden-sm hidden-tablet">The Automated... »</span>
</a>
</li>
<li><a href="#">Back to top</a></li>
</ul>
<p>
</p>
</div>
</footer>
</body>
</html>