-
Notifications
You must be signed in to change notification settings - Fork 2
/
ci.html
220 lines (207 loc) · 12.2 KB
/
ci.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
<!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="generator" content="Docutils 0.18.1: http://docutils.sourceforge.net/" />
<title>Continuous Integration — SpacePy v0.7.0 Manual</title>
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=b76e3c8a" />
<link rel="stylesheet" type="text/css" href="_static/sphinxdoc.css?v=92e3d466" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css?v=fd3f3429" />
<link rel="stylesheet" type="text/css" href="_static/plot_directive.css" />
<script src="_static/documentation_options.js?v=fe7df9b0"></script>
<script src="_static/doctools.js?v=9a2dae69"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script type="text/javascript" src="_static/copybutton.js"></script>
<link rel="icon" href="_static/spacepy_favicon.ico"/>
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="spacepy" href="autosummary/spacepy.html" />
<link rel="prev" title="spacepy_testing.testsdir" href="autosummary/spacepy_testing.testsdir.html" />
</head><body>
<div style="background-color: white; text-align: left; padding: 10px 10px 15px 15px">
<a href="index.html"><img src="_static/spacepy_logo.jpg" border="0" alt="spacepy_logo"/></a>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
accesskey="I">index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="autosummary/spacepy.html" title="spacepy"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="autosummary/spacepy_testing.testsdir.html" title="spacepy_testing.testsdir"
accesskey="P">previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="continuous-integration">
<h1>Continuous Integration<a class="headerlink" href="#continuous-integration" title="Link to this heading">¶</a></h1>
<p>SpacePy uses <a class="reference external" href="https://docs.github.com/en/actions">GitHub Actions</a>
for continuous integration. Most of the relevant information is
checked into the repository: the configuration file <a class="reference external" href="https://github.com/spacepy/spacepy/blob/main/.github/workflows/ci.yml">CI.yml</a>
manages the CI process, which ultimately runs <a class="reference external" href="https://github.com/spacepy/spacepy/blob/main/tests/test_all.py">the unit tests</a>. However
a few elements of the setup are not in the repository and are
documented here. This may be useful if this ever has to be set up in
the future, or if you want to run SpacePy CI tests on your fork before
opening a pull request.</p>
<nav class="contents local" id="contents">
<ul class="simple">
<li><p><a class="reference internal" href="#initial-run" id="id2">Initial run</a></p></li>
<li><p><a class="reference internal" href="#merging-rules" id="id3">Merging rules</a></p></li>
<li><p><a class="reference internal" href="#rerunning-ci-on-a-pr" id="id4">Rerunning CI on a PR</a></p></li>
<li><p><a class="reference internal" href="#cacheing" id="id5">Cacheing</a></p></li>
<li><p><a class="reference internal" href="#usage" id="id6">Usage</a></p></li>
</ul>
</nav>
<section id="initial-run">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Initial run</a><a class="headerlink" href="#initial-run" title="Link to this heading">¶</a></h2>
<p>A workflow cannot be run <a class="reference external" href="https://github.community/t/workflow-dispatch-event-not-working/128856/2">until it has been run once against the
default branch</a> (<code class="docutils literal notranslate"><span class="pre">main</span></code>). This makes
it somewhat hard to test the workflow before merging; in SpacePy this was
handled by merging a tiny workflow first (PR <a class="reference external" href="https://github.com/spacepy/spacepy/pull/496">496</a>).</p>
<p>Once this first run has been made, updated versions of the workflow
can be run from topic branches. It will show up under the <code class="docutils literal notranslate"><span class="pre">Actions</span></code>
tab of a repository and the branch to use can be selected. It is also
possible to specify a branch <a class="reference external" href="https://github.community/t/workflow-dispatch-workflow-not-showing-in-actions-tab/130088/15">by using the REST API</a>; you will need <a class="reference external" href="https://docs.github.com/engithub/authenticating-to-github/creating-a-personal-access-token">an access token</a> with
<code class="docutils literal notranslate"><span class="pre">workflow</span></code> scope.</p>
</section>
<section id="merging-rules">
<h2><a class="toc-backref" href="#id3" role="doc-backlink">Merging rules</a><a class="headerlink" href="#merging-rules" title="Link to this heading">¶</a></h2>
<p>PRs require CI to pass before merging; this is managed with a <a class="reference external" href="https://docs.github.com/en/github/administering-a-repository/managing-a-branch-protection-rule">branch
protection rule</a>
(<code class="docutils literal notranslate"><span class="pre">Settings</span></code> from the tab at the top of a repository, <code class="docutils literal notranslate"><span class="pre">Branches</span></code> from
the left menu.) The relevant choices is “Require status checks to pass
before merging.” Every variant of the unit testing job (<code class="docutils literal notranslate"><span class="pre">test</span> <span class="pre">(2.7,</span>
<span class="pre">ubuntu-18.04...</span></code> etc.) will be in the list of checks; leave these alone and
select only the <code class="docutils literal notranslate"><span class="pre">All</span> <span class="pre">tests</span></code> job. The name of this won’t change and it
will always depend on <em>all</em> the jobs in the workflow.
“Require branches to be up to date” should <em>not</em> be selected;
this encourages merging rather than our preferred rebase, and the tests
will run against a (temporary) merge regardless.</p>
</section>
<section id="rerunning-ci-on-a-pr">
<h2><a class="toc-backref" href="#id4" role="doc-backlink">Rerunning CI on a PR</a><a class="headerlink" href="#rerunning-ci-on-a-pr" title="Link to this heading">¶</a></h2>
<p>There is no way to manually trigger a workflow run on a pull request.
SpacePy’s CI workflow is set up to <a class="reference external" href="https://docs.github.com/en/actions/reference/events-that-trigger-workflows#pull_request">trigger the workflow</a> when a PR is marked ready for review, so one way to
force a run is to mark the PR as a draft, and then as ready again.</p>
<p>Note that a PR will not trigger the CI <a class="reference external" href="https://github.community/t/run-actions-on-pull-requests-with-merge-conflicts/17104">if there is a merge conflict</a>.</p>
</section>
<section id="cacheing">
<h2><a class="toc-backref" href="#id5" role="doc-backlink">Cacheing</a><a class="headerlink" href="#cacheing" title="Link to this heading">¶</a></h2>
<p>Dependencies for CI are stored in two caches: one for all pip
dependencies, and one for the NASA CDF library. This minimizes CI time
use for building dependencies.</p>
<p>Caches expire weekly (the week begins at 00 Monday, UTC). Caches can
also be force-expired by incrementing the versions in <code class="docutils literal notranslate"><span class="pre">ci.yml</span></code> for
the pip and/or CDF cache. Unfortunately this does require pushing a
commit.</p>
</section>
<section id="usage">
<h2><a class="toc-backref" href="#id6" role="doc-backlink">Usage</a><a class="headerlink" href="#usage" title="Link to this heading">¶</a></h2>
<p>SpacePy administrators can view the usage minutes, storage (for caches),
etc. on our <a class="reference external" href="https://github.com/organizations/spacepy/settings/billing">billing page</a>.</p>
<hr class="docutils" />
<dl class="field-list simple">
<dt class="field-odd">Release<span class="colon">:</span></dt>
<dd class="field-odd"><p>0.7.0</p>
</dd>
<dt class="field-even">Doc generation date<span class="colon">:</span></dt>
<dd class="field-even"><p>Nov 08, 2024</p>
</dd>
</dl>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p class="logo"><a href="index.html">
<img class="logo" src="_static/logo.png" alt="Logo"/>
</a></p>
<div>
<h3><a href="index.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Continuous Integration</a><ul>
<li><a class="reference internal" href="#initial-run">Initial run</a></li>
<li><a class="reference internal" href="#merging-rules">Merging rules</a></li>
<li><a class="reference internal" href="#rerunning-ci-on-a-pr">Rerunning CI on a PR</a></li>
<li><a class="reference internal" href="#cacheing">Cacheing</a></li>
<li><a class="reference internal" href="#usage">Usage</a></li>
</ul>
</li>
</ul>
</div>
<div>
<h4>Previous topic</h4>
<p class="topless"><a href="autosummary/spacepy_testing.testsdir.html"
title="previous chapter">spacepy_testing.testsdir</a></p>
</div>
<div>
<h4>Next topic</h4>
<p class="topless"><a href="autosummary/spacepy.html"
title="next chapter">spacepy</a></p>
</div>
<div role="note" aria-label="source link">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/ci.rst.txt"
rel="nofollow">Show Source</a></li>
</ul>
</div>
<search id="searchbox" style="display: none" role="search">
<h3 id="searchlabel">Quick search</h3>
<div class="searchformwrapper">
<form class="search" action="search.html" method="get">
<input type="text" name="q" aria-labelledby="searchlabel" autocomplete="off" autocorrect="off" autocapitalize="off" spellcheck="false"/>
<input type="submit" value="Go" />
</form>
</div>
</search>
<script>document.getElementById('searchbox').style.display = "block"</script>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="related" role="navigation" aria-label="related navigation">
<h3>Navigation</h3>
<ul>
<li class="right" style="margin-right: 10px">
<a href="genindex.html" title="General Index"
>index</a></li>
<li class="right" >
<a href="py-modindex.html" title="Python Module Index"
>modules</a> |</li>
<li class="right" >
<a href="autosummary/spacepy.html" title="spacepy"
>next</a> |</li>
<li class="right" >
<a href="autosummary/spacepy_testing.testsdir.html" title="spacepy_testing.testsdir"
>previous</a> |</li>
<li><a href="https://spacepy.github.io/"">homepage</a>| </li>
<li><a href="https://github.com/spacepy/spacepy">development</a>| </li>
<li><a href="search.html">search</a>| </li>
<li><a href="index.html">documentation </a> »</li>
<li class="nav-item nav-item-this"><a href="">Continuous Integration</a></li>
</ul>
</div>
<div class="footer" role="contentinfo">
© Copyright 2011-2024, The SpacePy Team.
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 7.3.7.
</div>
</body>
</html>