Repository navigation
Expand file tree
/
Copy pathGatekeeping.html
More file actions
670 lines (526 loc) · 43.8 KB
/
Copy pathGatekeeping.html
File metadata and controls
670 lines (526 loc) · 43.8 KB
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
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
<!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>Gatekeeping a Pull Request — MantidProject main documentation</title>
<script data-cfasync="false">
document.documentElement.dataset.mode = localStorage.getItem("mode") || "";
document.documentElement.dataset.theme = localStorage.getItem("theme") || "";
</script>
<!--
this give us a css class that will be invisible only if js is disabled
-->
<noscript>
<style>
.pst-js-only { display: none !important; }
</style>
</noscript>
<!-- Loaded before other Sphinx assets -->
<link href="_static/styles/theme.css?digest=18bd87630a240e9c25be" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=18bd87630a240e9c25be" rel="stylesheet" />
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=03e43079" />
<link rel="stylesheet" type="text/css" href="_static/css/style.css?v=562d7d41" />
<!-- So that users can add custom icons -->
<script defer src="_static/scripts/fontawesome.js?digest=18bd87630a240e9c25be"></script>
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=18bd87630a240e9c25be" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=18bd87630a240e9c25be" />
<script src="_static/documentation_options.js?v=a8da1a53"></script>
<script src="_static/doctools.js?v=fd6eb6e6"></script>
<script src="_static/sphinx_highlight.js?v=6ffebe34"></script>
<script>DOCUMENTATION_OPTIONS.pagename = 'Gatekeeping';</script>
<script>DOCUMENTATION_OPTIONS.search_as_you_type = false;</script>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Writing Performance Tests" href="WritingPerformanceTests.html" />
<link rel="prev" title="Reviewing a Pull Request" href="ReviewingAPullRequest.html" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="docsearch:language" content="en">
<link rel="icon" sizes="32x32" href="_static/images/favicon.ico">
</head>
<body data-default-mode="">
<div id="pst-skip-link" class="skip-link d-print-none"><a href="#main-content">Skip to main content</a></div>
<div id="pst-scroll-pixel-helper"></div>
<button type="button" class="btn rounded-pill" id="pst-back-to-top">
<i class="fa-solid fa-arrow-up"></i>Back to top</button>
<dialog id="pst-search-dialog">
<form class="bd-search d-flex align-items-center"
action="search.html"
method="get">
<i class="fa-solid fa-magnifying-glass"></i>
<input type="search"
class="form-control"
name="q"
placeholder="Search the docs ..."
aria-label="Search the docs ..."
autocomplete="off"
autocorrect="off"
autocapitalize="off"
spellcheck="false"/>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd>K</kbd></span>
</form>
</dialog>
<div class="pst-async-banner-revealer d-none">
<aside id="bd-header-version-warning" class="d-none d-print-none" aria-label="Version warning"></aside>
</div>
<header id="pst-header" class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
<button type="button" class="pst-navbar-icon sidebar-toggle primary-toggle" aria-label="Site navigation">
<span class="fa-solid fa-bars"></span>
</button>
<div class="col-lg-3 navbar-header-items__start">
<div class="navbar-item">
<a class="navbar-brand logo" href="index.html">
<img src="_static/images/mantid_logo_light.png" class="logo__image only-light" alt="Logo image">
<img src="_static/images/mantid_logo_dark.png" class="logo__image only-dark" alt="Logo image">
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item"><ul id="navbar-main-elements" class="navbar-nav">
<li class="nav-item">
<a class="reference internal nav-link" href="https://download.mantidproject.org">Downloads</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/nightly/tutorials/">Tutorials</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org">User Docs</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://developer.mantidproject.org">Develop</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/release/">Release notes</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://www.mantidproject.org/contact">Contact Us</a>
</li>
</ul></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item navbar-persistent--container">
<button type="button" class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
</div>
<div class="navbar-item">
<div class="theme-switch-container dropdown pst-js-only" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Color mode">
<button type="button" class="btn btn-sm nav-link pst-navbar-icon theme-switch-button dropdown-toggle" aria-label="Color mode" data-bs-toggle="dropdown">
<i class="theme-switch fa-solid fa-sun fa-lg fa-fw" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg fa-fw" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg fa-fw" data-mode="auto" title="System Settings"></i>
</button>
<ul class="dropdown-menu dropdown-menu-end">
<li><button type="button" class="dropdown-item d-flex align-items-center theme-change-button" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg fa-fw me-1"></i>System Settings</button></li>
<li><button type="button" class="dropdown-item d-flex align-items-center theme-change-button" data-mode="light"><i class="fa-solid fa-sun fa-lg fa-fw me-1"></i>Light</button></li>
<li><button type="button" class="dropdown-item d-flex align-items-center theme-change-button" data-mode="dark"><i class="fa-solid fa-moon fa-lg fa-fw me-1"></i>Dark</button></li>
</ul>
</div></div>
<div class="navbar-item"><ul id="navbar-icon-links" class="navbar-nav" aria-label="Icon Links">
<li class="nav-item">
<a class="nav-link" href="https://github.com/mantidproject/mantid" rel="noopener" target="_blank" title="GitHub">
<span><i class="fab fa-github-square"></i></span>
<label class="sr-only">GitHub</label>
</a>
</li>
</ul></div>
</div>
</div>
<div class="navbar-persistent--mobile">
<button type="button" class="btn search-button-field search-button__button pst-js-only" title="Search" aria-label="Search" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="fa-solid fa-magnifying-glass"></i>
<span class="search-button__default-text">Search</span>
<span class="search-button__kbd-shortcut"><kbd class="kbd-shortcut__modifier">Ctrl</kbd>+<kbd class="kbd-shortcut__modifier">K</kbd></span>
</button>
</div>
<button type="button" class="pst-navbar-icon sidebar-toggle secondary-toggle" aria-label="On this page">
<span class="fa-solid fa-outdent"></span>
</button>
</div>
</header>
<div class="bd-container">
<div class="bd-container__inner bd-page-width">
<dialog id="pst-primary-sidebar-modal"></dialog>
<div id="pst-primary-sidebar" class="bd-sidebar-primary bd-sidebar">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item"><ul id="navbar-main-elements" class="navbar-nav">
<li class="nav-item">
<a class="reference internal nav-link" href="https://download.mantidproject.org">Downloads</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/nightly/tutorials/">Tutorials</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org">User Docs</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://developer.mantidproject.org">Develop</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://docs.mantidproject.org/release/">Release notes</a>
</li>
<li class="nav-item">
<a class="reference internal nav-link" href="https://www.mantidproject.org/contact">Contact Us</a>
</li>
</ul></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<div class="theme-switch-container dropdown pst-js-only" data-bs-toggle="tooltip" data-bs-placement="bottom" title="Color mode">
<button type="button" class="btn btn-sm nav-link pst-navbar-icon theme-switch-button dropdown-toggle" aria-label="Color mode" data-bs-toggle="dropdown">
<i class="theme-switch fa-solid fa-sun fa-lg fa-fw" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg fa-fw" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg fa-fw" data-mode="auto" title="System Settings"></i>
</button>
<ul class="dropdown-menu dropdown-menu-end">
<li><button type="button" class="dropdown-item d-flex align-items-center theme-change-button" data-mode="auto"><i class="fa-solid fa-circle-half-stroke fa-lg fa-fw me-1"></i>System Settings</button></li>
<li><button type="button" class="dropdown-item d-flex align-items-center theme-change-button" data-mode="light"><i class="fa-solid fa-sun fa-lg fa-fw me-1"></i>Light</button></li>
<li><button type="button" class="dropdown-item d-flex align-items-center theme-change-button" data-mode="dark"><i class="fa-solid fa-moon fa-lg fa-fw me-1"></i>Dark</button></li>
</ul>
</div></div>
<div class="navbar-item"><ul id="navbar-icon-links" class="navbar-nav" aria-label="Icon Links">
<li class="nav-item">
<a class="nav-link" href="https://github.com/mantidproject/mantid" rel="noopener" target="_blank" title="GitHub">
<span><i class="fab fa-github-square"></i></span>
<label class="sr-only">GitHub</label>
</a>
</li>
</ul></div>
</div>
</div>
<div class="sidebar-primary-items__start sidebar-primary__section">
<div class="sidebar-primary-item pst-sidebar-collapse"><button type="button" id="pst-collapse-sidebar-button" aria-expanded="true" aria-controls="pst-primary-sidebar">
<svg class="pst-icon" role="img" aria-hidden="true" focusable="false" viewBox="0 0 16 16" xmlns="http://www.w3.org/2000/svg">
<path fill="currentColor" d="M3 15.5C2.36232 15.5 1.74874 15.2564 1.28478 14.8189C0.820828 14.3815 0.541576 13.7832 0.504167 13.1467L0.5 13L0.5 3C0.499965 2.36232 0.743605 1.74874 1.18107 1.28478C1.61854 0.820828 2.21676 0.541576 2.85333 0.504167L3 0.5L13 0.5C13.6377 0.499965 14.2513 0.743605 14.7152 1.18107C15.1792 1.61854 15.4584 2.21676 15.4958 2.85333L15.5 3L15.5 13C15.5 13.6377 15.2564 14.2513 14.8189 14.7152C14.3815 15.1792 13.7832 15.4584 13.1467 15.4958L13 15.5L3 15.5ZM3 13.8333L10.5 13.8333L10.5 2.16667L3 2.16667C2.79589 2.16669 2.59889 2.24163 2.44636 2.37726C2.29383 2.5129 2.19638 2.69979 2.1725 2.9025L2.16667 3L2.16667 13C2.16669 13.2041 2.24163 13.4011 2.37726 13.5536C2.5129 13.7062 2.69979 13.8036 2.9025 13.8275L3 13.8333ZM6.65583 10.325L6.5775 10.2558L4.91083 8.58917C4.76735 8.44567 4.68116 8.25476 4.66843 8.05223C4.65569 7.84971 4.71729 7.6495 4.84167 7.48917L4.91083 7.41083L6.5775 5.74417C6.72747 5.59471 6.9287 5.50794 7.14032 5.50148C7.35194 5.49502 7.55809 5.56935 7.7169 5.70937C7.8757 5.8494 7.97525 6.04463 7.99533 6.25539C8.01541 6.46616 7.95451 6.67667 7.825 6.84417L7.75583 6.9225L6.67917 8L7.75583 9.0775C7.89931 9.22099 7.98551 9.41191 7.99824 9.61443C8.01097 9.81695 7.94938 10.0172 7.825 10.1775L7.75583 10.2558C7.61234 10.3993 7.42142 10.4855 7.2189 10.4982C7.01638 10.511 6.81617 10.4494 6.65583 10.325Z"/>
</svg>
<span class="pst-collapse-sidebar-label">Collapse Sidebar</span>
<span class="pst-expand-sidebar-label">Expand Sidebar</span>
</button></div>
<div class="sidebar-primary-item">
<nav class="bd-docs-nav bd-links"
aria-label="Section Navigation">
<p class="bd-links__title" role="heading" aria-level="1">Section Navigation</p>
<div class="bd-toc-item navbar-nav"></div>
</nav></div>
</div>
<div class="sidebar-primary-items__end sidebar-primary__section">
<div class="sidebar-primary-item">
<div id="ethical-ad-placement"
class="flat"
data-ea-publisher="readthedocs"
data-ea-type="readthedocs-sidebar"
data-ea-manual="true">
</div></div>
</div>
</div>
<main id="main-content" class="bd-main" role="main">
<div class="bd-content">
<div class="bd-article-container">
<div class="bd-header-article d-print-none">
<div class="header-article-items header-article__inner">
<div class="header-article-items__start">
<div class="header-article-item">
<nav aria-label="Breadcrumb" class="d-print-none">
<ul class="bd-breadcrumbs">
<li class="breadcrumb-item breadcrumb-home">
<a href="index.html" class="nav-link" aria-label="Home">
<i class="fa-solid fa-home"></i>
</a>
</li>
<li class="breadcrumb-item active" aria-current="page"><span class="ellipsis">Gatekeeping a Pull Request</span></li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="gatekeeping-a-pull-request">
<span id="gatekeeping"></span><h1>Gatekeeping a Pull Request<a class="headerlink" href="#gatekeeping-a-pull-request" title="Link to this heading">#</a></h1>
<p>The final step in our <a class="reference internal" href="GitWorkflow.html#gitworkflow"><span class="std std-ref">development workflow</span></a> after a <a class="reference internal" href="ReviewingAPullRequest.html#reviewingapullrequest"><span class="std std-ref">pull request has been reviewed</span></a> is gatekeeping. This is second review stage where a senior developer / code owner does a final check of the work before merging it to the <code class="docutils literal notranslate"><span class="pre">main</span></code> or <code class="docutils literal notranslate"><span class="pre">release-next</span></code> branch.</p>
<section id="purpose">
<h2>Purpose<a class="headerlink" href="#purpose" title="Link to this heading">#</a></h2>
<p>This document offers some guidance for gatekeepers as to what to look for and some quirks of Mantid to be aware of that the first reviewer may have missed. There are 3 main purposes to gatekeeping:</p>
<ul class="simple">
<li><p><strong>Audit:</strong> A detailed code review is generally not required as long as the first stage reviewer has done a thorough job - one of the main purposes of the gatekeeping role is to ensure that this is the case, i.e. that the review process has been followed correctly and all of the appropriate checks have been made.</p></li>
<li><p><strong>Code quality:</strong> The other main purpose is to ensure all code changes have been seen by an experienced developer. We very much encourage new/junior team members to take part in first-stage reviews, so having this second stage ensures we have a chance to catch things that a newer team member may not be aware of.</p></li>
<li><p><strong>Knowledge sharing:</strong> An additional benefit of the process is the opportunity for more experienced developers to offer advice and spot learning and development opportunities for individuals and/or things the whole team could benefit from. Depending on your capacity and interest in this do feel free to offer tips and/or feed into team processes or training materials as you think appropriate.</p></li>
</ul>
</section>
<section id="with-great-power-comes-great-responsibility">
<h2>With great power comes great responsibility<a class="headerlink" href="#with-great-power-comes-great-responsibility" title="Link to this heading">#</a></h2>
<p><em>Be very careful not to push to</em> <code class="docutils literal notranslate"><span class="pre">main</span></code> or <code class="docutils literal notranslate"><span class="pre">release-next</span></code></p>
<ul class="simple">
<li><p>When you are made a gatekeeper on the project you will be given <strong>full, unprotected access to the</strong> <code class="docutils literal notranslate"><span class="pre">main</span></code> <strong>branch</strong>. This means you lose the normal protection that stops you being able to push directly to the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch - you therefore need to be careful at all times that you do not accidentally push to <code class="docutils literal notranslate"><span class="pre">main</span></code>, e.g. when you are using Git in your terminal or Git GUI.</p></li>
<li><p>You should be enough of a Git expert to know the implications of directly pushing to a branch, including being able to overwrite a branch completely with the history of another branch, which of course would be pretty catastrophic if done to <code class="docutils literal notranslate"><span class="pre">main</span></code>. You should have solid working practices with Git that ensure you are never likely to do this. Working on a fork is recommended, and some of the <a class="reference internal" href="GitConfig.html#gitconfig"><span class="std std-ref">recommended config</span></a> regarding default behaviour for <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">push</span></code> will also help (although recent versions of Git are much safer by default in this regard so in reality you are unlikely to have problems).</p></li>
<li><p>Of course, you should never deliberately make any changes directly on <code class="docutils literal notranslate"><span class="pre">main</span></code>, either via Github or a direct push to <code class="docutils literal notranslate"><span class="pre">main</span></code> - always raise a pull request regardless of how minor the change is otherwise you run a high risk of it not passing the CI tests and breaking the build for all developers.</p></li>
</ul>
</section>
<section id="performing-a-merge-on-github">
<h2>Performing a merge on Github<a class="headerlink" href="#performing-a-merge-on-github" title="Link to this heading">#</a></h2>
<ul class="simple">
<li><p>Gatekeepers should use <code class="docutils literal notranslate"><span class="pre">Squash</span> <span class="pre">and</span> <span class="pre">merge</span></code> for all pull requests. This option:</p>
<ul>
<li><p>Helps maintain a tidy Git history by combining all of the commits in a PR into a single commit on the destination branch.</p></li>
<li><p>Ensures that every commit on the destination branch is a complete, CI-tested change that compile. This keeps the Git history self-consistent and makes it easier to use <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">bisect</span></code> to track down regressions.</p></li>
<li><p>Makes it easier to identify which PR introduced a failure in a nightly build.</p></li>
</ul>
</li>
<li><p>The <code class="docutils literal notranslate"><span class="pre">Squash</span> <span class="pre">and</span> <span class="pre">merge</span></code> button will be green if all checks have passed and there is an approved review. The button will be red if this is not the case but you have the power to override it and merge anyway. It is not recommended to do this but very occasionally may be needed if, for example, it is urgent and being held up by an unreliable test you are certain is unrelated. If you do need to do this, make sure you add a clear comment describing why.</p></li>
<li><p>When you click the button you will get the chance to edit the commit message before committing. Feel free to edit the commit message if the PR title can be improved upon. If required, add any useful information to the <code class="docutils literal notranslate"><span class="pre">Extended</span> <span class="pre">description</span></code> box.</p></li>
<li><p>Click <code class="docutils literal notranslate"><span class="pre">Confirm</span> <span class="pre">merge</span> <span class="pre">(squash)</span></code> to merge the commit to the destination branch.</p></li>
<li><p>If a PR is approved but still finishing its CI checks then the button will read <code class="docutils literal notranslate"><span class="pre">Enable</span> <span class="pre">auto-merge</span> <span class="pre">(squash)</span></code>. Use this if you are happy for the PR to be automatically merged once it passes all the CI checks.</p></li>
</ul>
</section>
<section id="don-t-panic">
<h2>Don’t panic<a class="headerlink" href="#don-t-panic" title="Link to this heading">#</a></h2>
<p>There is a lot here to consider but bear in mind that you are not expected to catch everything. Things will always slip through and we have good processes in place to catch them, and we can always revert changes if necessary. You have been invited to be a gatekeeper because you have valuable knowledge that we think the rest of the team can benefit from, so please share what you can :)</p>
</section>
<section id="things-to-check">
<h2>Things to check<a class="headerlink" href="#things-to-check" title="Link to this heading">#</a></h2>
<section id="tips">
<h3>Tips<a class="headerlink" href="#tips" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>Generally I will start with a quick scan to the bottom of the comments to check the reviewers final comment - often this can inform what else to look for and save time (and it is good to encourage developers to write a concise summary of everything considered in the review in a final comment to make the gatekeeping process quicker).</p></li>
<li><p>Have a quick scan to see what files are changed - this informs how widespread the change is. Use tools to help - Github has a side bar that displays a file hierarchy; Octotree is a useful plugin that also shows the number of lines changed in each file, and the Pro version has some nice functionality to show which files you’ve marked as viewed.</p></li>
<li><p>Be aware that other gatekeepers may be looking at PRs at the same time as you, so if you think you will be spending any significant time doing your review, assign yourself as a reviewer and/or put a comment on it so that other gatekeepers know not to look at it (particularly if you think you might need to ask for changes, because another gatekeeper might merge it in the meantime!).</p></li>
</ul>
</section>
<section id="destination-branch">
<h3>Destination branch<a class="headerlink" href="#destination-branch" title="Link to this heading">#</a></h3>
<p><em>Be aware of where we are in the development/release cycle</em></p>
<ul class="simple">
<li><p>Check that the destination branch is correct. During development sprints, the destination branch should be <code class="docutils literal notranslate"><span class="pre">main</span></code>. During the release period, it may be <code class="docutils literal notranslate"><span class="pre">main</span></code> or <code class="docutils literal notranslate"><span class="pre">release-next</span></code> - ensure you are familiar with the release process and know the differences.</p></li>
<li><p>Be more picky in the run up to release freeze - if large or risky changes are being made very close to release, question whether they can wait till the next release.</p></li>
<li><p>The milestone should be set appropriately for the destination branch. If either doesn’t look correct, query it.</p></li>
<li><p>Use extra caution when merging into <code class="docutils literal notranslate"><span class="pre">release-next</span></code>, particularly after release freeze when we should only be merging things that are critical and are considered “safe” fixes. The later we get into the release sprint, the more picky we need to be. If a PR can wait till the next release, get the developer to change the destination branch to <code class="docutils literal notranslate"><span class="pre">main</span></code>.</p></li>
<li><p>If we are on very close to releasing, further merges to <code class="docutils literal notranslate"><span class="pre">release-next</span></code> may miss the build and be lost entirely. Check with the release manager.</p></li>
</ul>
</section>
<section id="general-checks">
<h3>General checks<a class="headerlink" href="#general-checks" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>Check that the PR description and testing instructions are clear.</p></li>
<li><p>Check that the reviewer seems to have done a thorough job on the functional testing and code review - feel free to ask if not clear.</p></li>
<li><p>Check that everything has been added/updated if applicable, e.g. release notes, unit tests, system tests, documentation, developer documentation, unscripted testing documentation.</p></li>
<li><p>Check that all reviewer comments have been addressed - in particular if there are additional comments from someone who is not the approver, because these can easily get missed after one person approves. Also check if any additional reviewers have been requested who have not commented.</p></li>
<li><p>If a PR makes changes that look like they need scientific validation it might be worth querying what has been done or what plans are in place for this.</p></li>
<li><p>Check the list of changed files looks sensible - sometimes developers mistakenly <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code> things by mistake e.g. local file changes, temp files etc. Query anything that looks out of place.</p></li>
</ul>
</section>
<section id="testing">
<h3>Testing<a class="headerlink" href="#testing" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>Check that all functional code changes are covered by unit tests (this might be existing tests or new tests might be required with the change).</p></li>
<li><p>Check that functional testing has been included in the PR description and is clear and is sufficient. Developers will often state that it just needs to pass the automated tests, or that just code review is required. However, any change that affects functional code should have some way of manually testing it so I would normally expect to see something here unless there is a good reason otherwise.</p></li>
</ul>
</section>
<section id="code-quality">
<h3>Code quality<a class="headerlink" href="#code-quality" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>Have a brief scan of some of the changes to check that they adhere to standards.</p></li>
<li><p>Consider any design decisions that have been made and if these are appropriate and not breaking any obvious design patterns, e.g. it is common to see MVP being broken where logic is added to the view and is not testable; the lack of tests can be an indicator here. Is there any pollution of e.g. Qt in a non-Qt class; again this may make testing more difficult/complicated.</p></li>
<li><p>Have a brief check that any tests look to be of good quality; unit tests should be clear and test things in isolation. Check for appropriate use of mocks.</p></li>
<li><p>Keep an eye out for any other code smells - unclear tests, files/classes too long, long comments etc.</p></li>
</ul>
</section>
<section id="deeper-checks">
<h3>Deeper checks<a class="headerlink" href="#deeper-checks" title="Link to this heading">#</a></h3>
<p>A more thorough code review may be required in some situations, e.g.:</p>
<ul class="simple">
<li><p>the change is to core components or a wide range of components;</p></li>
<li><p>the <code class="docutils literal notranslate"><span class="pre">Needs</span> <span class="pre">attention</span></code> label has been applied;</p></li>
<li><p>the reviewer is more junior or unfamiliar with the area of code;</p></li>
<li><p>the change involves considerable design changes/additions.</p></li>
</ul>
<p>A quick scan of the files changed can indicate whether the change is confined to a particular component or more widespread.</p>
</section>
<section id="version-control">
<h3>Version control<a class="headerlink" href="#version-control" title="Link to this heading">#</a></h3>
<p>While not vital and often not something I’d ask for changes on, it is good to keep an eye on how clean and informative developers are keeping their Git commit history and offer tips, particularly to new developers, to help them improve their processes. This is sometimes the only chance to help some sole developers realise they could be working in a much more efficient manner. Things you might want to look for and offer advice on are:</p>
<ul class="simple">
<li><p>Nice clean history, in particular avoiding merge commits from <code class="docutils literal notranslate"><span class="pre">main</span></code> or the remote feature branch into the local feature branch - recommend rebase instead, and setting up config so this is done automatically.</p></li>
<li><p>Clear commit messages, with a short title and more detailed message body if appropriate.</p></li>
<li><p>Commit messages that clearly describe the actual changes - try to discourage comments to reference the review such as “add changes from review” and encourage describing the actual changes instead.</p></li>
<li><p>Commits that nicely encapsulate increments of work - if developers are making multiple subsequent commits that should logically be part of a previous commit encourage use of <code class="docutils literal notranslate"><span class="pre">amend</span></code> and <code class="docutils literal notranslate"><span class="pre">fixup</span></code>.</p></li>
<li><p>Using <code class="docutils literal notranslate"><span class="pre">#re</span></code> or <code class="docutils literal notranslate"><span class="pre">#refs</span></code> in the comment where appropriate (either title or body; we have a mix of styles but a developer should pick one and be consistent).</p></li>
</ul>
</section>
</section>
<section id="fixing-a-merge-conflict-between-main-and-a-protected-branch">
<span id="fixprotectedbranchmergeconflict"></span><h2>Fixing a merge conflict between <code class="docutils literal notranslate"><span class="pre">main</span></code> and a protected branch<a class="headerlink" href="#fixing-a-merge-conflict-between-main-and-a-protected-branch" title="Link to this heading">#</a></h2>
<p>There may occasionally be a merge conflict when the automated “Merge protected branches” workflow attempts to merge a protected branch into <code class="docutils literal notranslate"><span class="pre">main</span></code>. Since all PRs are now squash merged, these conflicts must be resolved by performing the merge directly on <code class="docutils literal notranslate"><span class="pre">main</span></code> so that the merge commit is preserved. The instructions below detail how to fix the conflict, using the <code class="docutils literal notranslate"><span class="pre">release-next</span></code> branch as an example.</p>
<p>Assuming you have the following remote setup:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>$<span class="w"> </span>git<span class="w"> </span>remote<span class="w"> </span>-v
origin<span class="w"> </span>https://github.com/mantidproject/mantid.git<span class="w"> </span><span class="o">(</span>fetch<span class="o">)</span>
origin<span class="w"> </span>https://github.com/mantidproject/mantid.git<span class="w"> </span><span class="o">(</span>push<span class="o">)</span>
</pre></div>
</div>
<p>you can follow these instructions to fix the merge conflict:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>fetch<span class="w"> </span>origin
git<span class="w"> </span>checkout<span class="w"> </span>main
git<span class="w"> </span>pull<span class="w"> </span>origin<span class="w"> </span>main
git<span class="w"> </span>merge<span class="w"> </span>origin/release-next
</pre></div>
</div>
<p>resolve any conflicts, then:</p>
<div class="highlight-bash notranslate"><div class="highlight"><pre><span></span>git<span class="w"> </span>add<span class="w"> </span><resolved-files>
git<span class="w"> </span>commit
git<span class="w"> </span>push<span class="w"> </span>origin<span class="w"> </span>main
</pre></div>
</div>
</section>
<section id="specific-quirks-of-mantid">
<h2>Specific quirks of Mantid<a class="headerlink" href="#specific-quirks-of-mantid" title="Link to this heading">#</a></h2>
<p>There are often multiple and/or confusing ways to do things in Mantid and it is not always clear which is the right approach, particularly when there is a lot of legacy code following old outdated approaches. This section attempts to point out some of the common areas where there can be pitfalls. There is no direct advice here, but if you see changes that include these things and don’t look ideal then it might be worth digging deeper.</p>
<section id="algorithms">
<h3>Algorithms<a class="headerlink" href="#algorithms" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>Workflow algorithms should only modify workspaces via calls to child algorithms; if you see one directly manipulating data in a workspace it is probably breaking the intention here and could have implications where the workspace history will be incomplete. There are already examples of this in Mantid so developers might follow the same pattern not realising that this is not the intended way of using workflow algorithms.</p></li>
<li><p>If algorithm outputs change it may be worth checking if the algorithm should be versioned if users will still require the old results to be reproducible.</p></li>
</ul>
</section>
<section id="workspaces">
<h3>Workspaces<a class="headerlink" href="#workspaces" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>Use of the ADS can be inconsistent. A lot of code uses it unnecessarily and workspaces are passed around by name assuming they will be in the ADS when actually this might be unnecessary and cause problems with algorithm history if a workspace doesn’t exist. Some algorithms have hacky code that dumps interim outputs into the ADS directly rather than using input/output properties, which again can cause problems with the history.</p></li>
<li><p>Workspace history is often overlooked in testing and can be easily messed up by mis-use of workflow algorithms and mis-use of ADS and input/output workspace properties. Note however that history doesn’t always work reliably anyway though.</p></li>
</ul>
</section>
<section id="workspace-groups">
<h3>Workspace Groups<a class="headerlink" href="#workspace-groups" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>Workspace groups are not handled particularly well in various parts of the code. In particular developers often forget to test with them and the workspace history can be confusing/incorrect.</p></li>
</ul>
</section>
<section id="idfs-and-ipfs">
<h3>IDFs and IPFs<a class="headerlink" href="#idfs-and-ipfs" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>These changes take effect as soon as they are merged to <code class="docutils literal notranslate"><span class="pre">main</span></code> - ensure the developer and their user(s) are aware of this. They may want to decouple these changes from code changes, and ensure backwards compatibility. Release notes may or may not be helpful (the changes are not tied to a release so in that case could be confusing, but some people prefer to add them because at least then the changes do get highlighted to users; it depends somewhat on the change and the audience).</p></li>
</ul>
</section>
<section id="unit-tests">
<h3>Unit tests<a class="headerlink" href="#unit-tests" title="Link to this heading">#</a></h3>
<ul class="simple">
<li><p>The main thing to look out for is that unit tests are small and test a minimal piece of functionality. Often newer developers might add tests that do a full reduction on real data and just checks some output numbers, which can be unclear what a correct output looks like. These might be better as system tests and/or it might be better for them to create dummy data and make the tests smaller and clearer.</p></li>
<li><p>Unit tests should be very quick, ideally under 1 second; push back if the developer is adding slower-running tests without a clear justification.</p></li>
<li><p>Calling algorithms in tests requires initialising framework. This is sometimes necessary but often it is better to use mocks.</p></li>
<li><p>Calling Python algorithms from C++ tests is not possible - either mock or create Python tests (calling C++ algorithms from Python works).</p></li>
<li><p>Creating Qt objects in tests can often cause problems - ideally MVP should mean we can mock out view components and not need Qt at all in unit tests, although sometimes it is hard to avoid without a big refactor. Some creation of Qt components also needs testing but this is often better done as system/integration type tests.</p></li>
</ul>
</section>
</section>
<section id="how-do-people-become-gatekeepers">
<h2>How do people become gatekeepers?<a class="headerlink" href="#how-do-people-become-gatekeepers" title="Link to this heading">#</a></h2>
<p>Gatekeepers are selected by the technical working group and/or local team leaders. We aim to have a good balance of gatekeepers from each contributing facility where possible.</p>
</section>
</section>
</article>
<footer class="prev-next-footer d-print-none">
<div class="prev-next-area">
<a class="left-prev"
href="ReviewingAPullRequest.html"
title="previous page">
<i class="fa-solid fa-angle-left"></i>
<div class="prev-next-info">
<p class="prev-next-subtitle">previous</p>
<p class="prev-next-title">Reviewing a Pull Request</p>
</div>
</a>
<a class="right-next"
href="WritingPerformanceTests.html"
title="next page">
<div class="prev-next-info">
<p class="prev-next-subtitle">next</p>
<p class="prev-next-title">Writing Performance Tests</p>
</div>
<i class="fa-solid fa-angle-right"></i>
</a>
</div>
</footer>
</div>
<dialog id="pst-secondary-sidebar-modal"></dialog>
<div id="pst-secondary-sidebar" class="bd-sidebar-secondary bd-toc"><div class="sidebar-secondary-items sidebar-secondary__inner">
<div class="sidebar-secondary-item">
<div
id="pst-page-navigation-heading-2"
class="page-toc tocsection onthispage">
<i class="fa-solid fa-list"></i> On this page
</div>
<nav id="pst-page-toc-nav" class="page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="pst-show_toc_level nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#purpose">Purpose</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#with-great-power-comes-great-responsibility">With great power comes great responsibility</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#performing-a-merge-on-github">Performing a merge on Github</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#don-t-panic">Don’t panic</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#things-to-check">Things to check</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#tips">Tips</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#destination-branch">Destination branch</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#general-checks">General checks</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#testing">Testing</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#code-quality">Code quality</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#deeper-checks">Deeper checks</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#version-control">Version control</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#fixing-a-merge-conflict-between-main-and-a-protected-branch">Fixing a merge conflict between <code class="docutils literal notranslate"><span class="pre">main</span></code> and a protected branch</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#specific-quirks-of-mantid">Specific quirks of Mantid</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#algorithms">Algorithms</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#workspaces">Workspaces</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#workspace-groups">Workspace Groups</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#idfs-and-ipfs">IDFs and IPFs</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#unit-tests">Unit tests</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#how-do-people-become-gatekeepers">How do people become gatekeepers?</a></li>
</ul>
</nav></div>
<div class="sidebar-secondary-item">
<div class="tocsection sourcelink">
<a href="_sources/Gatekeeping.rst.txt">
<i class="fa-solid fa-file-lines"></i> Show Source
</a>
</div>
</div>
</div></div>
</div>
<footer class="bd-footer-content">
</footer>
</main>
</div>
</div>
<!-- Scripts loaded after <body> so the DOM is not blocked -->
<script defer src="_static/scripts/bootstrap.js?digest=18bd87630a240e9c25be"></script>
<script defer src="_static/scripts/pydata-sphinx-theme.js?digest=18bd87630a240e9c25be"></script>
<footer class="bd-footer">
<div class="bd-footer__inner bd-page-width">
<div class="footer-items__start">
<div class="footer-item">
<p class="copyright">
© Copyright 2007-2026, Mantid.
<br/>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 9.1.0.
</p>
</div>
</div>
<div class="footer-items__end">
<div class="footer-item">
<p class="theme-version">
<!-- # L10n: Setting the PST URL as an argument as this does not need to be localized -->
Built with the <a href="https://pydata-sphinx-theme.readthedocs.io/en/stable/index.html">PyData Sphinx Theme</a> 0.23.0.
</p></div>
</div>
</div>
</footer>
</body>
</html>