-
Notifications
You must be signed in to change notification settings - Fork 7
/
developers.html
602 lines (587 loc) · 38 KB
/
developers.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
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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" /><meta name="generator" content="Docutils 0.19: https://docutils.sourceforge.io/" />
<title>Developers’ Guide — Clawpack 5.11.x documentation</title>
<link rel="stylesheet" href="_static/base.css" type="text/css" />
<link rel="stylesheet" href="_static/layout.css" type="text/css" />
<link rel="stylesheet" type="text/css" href="_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="_static/flasky.css" />
<link rel="stylesheet" type="text/css" href="_static/graphviz.css" />
<script data-url_root="./" id="documentation_options" src="_static/documentation_options.js"></script>
<script src="_static/jquery.js"></script>
<script src="_static/underscore.js"></script>
<script src="_static/_sphinx_javascript_frameworks_compat.js"></script>
<script src="_static/doctools.js"></script>
<script src="_static/sphinx_highlight.js"></script>
<link rel="shortcut icon" href="_static/clawicon.ico"/>
<link rel="author" title="About these documents" href="about.html" />
<link rel="index" title="Index" href="genindex.html" />
<link rel="search" title="Search" href="search.html" />
<link rel="next" title="Guide for updating this documentation" href="howto_doc.html" />
<link rel="prev" title="Understanding Pyclaw Classes" href="pyclaw/classes.html" />
</head><body>
<div id="main-wrapper" class="sphinx">
<div id="header-wrapper">
<section id="header">
<!-- <h1><a href="http://clawpack.org/">Clawpack</a></h1> -->
<h1><a href="http://clawpack.org/">Clawpack-5</a></h1>
<nav>
<ul>
<li>
<a href="contents.html">Docs</a>
</li>
<li>
<a href="installing.html">Install</a>
</li>
<li>
<a class="" href="http://clawpack.org/gallery/index.html">Gallery</a>
</li>
<li>
<a href="about.html">Citation</a>
</li>
<li>
<a class="active" href="http://github.com/clawpack">GitHub</a>
</li>
<li>
<a class="" href="community.html">Community</a>
</li>
<li>
<a class="" href="#">Contribute</a>
</li>
</ul>
</nav>
</section>
<div class="decoration"></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"
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="howto_doc.html" title="Guide for updating this documentation"
accesskey="N">next</a> |</li>
<li class="right" >
<a href="pyclaw/classes.html" title="Understanding Pyclaw Classes"
accesskey="P">previous</a> |</li>
<li class="nav-item nav-item-0"><a href="contents.html">Clawpack 5.11.x documentation</a> »</li>
<li class="nav-item nav-item-1"><a href="pyclaw/index.html" accesskey="U">PyClaw</a> »</li>
<li class="nav-item nav-item-this"><a href="">Developers’ Guide</a></li>
</ul>
</div>
<div class="document">
<div class="documentwrapper">
<div class="bodywrapper">
<div class="body" role="main">
<section id="developers-guide">
<span id="developers"></span><h1><a class="toc-backref" href="#id1" role="doc-backlink">Developers’ Guide</a><a class="headerlink" href="#developers-guide" title="Permalink to this heading">¶</a></h1>
<p>See also the following pages from <a class="reference internal" href="contents.html#contents-developers-resources"><span class="std std-ref">Developers’ resources</span></a>:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="howto_doc.html">Guide for updating this documentation</a></li>
<li class="toctree-l1"><a class="reference internal" href="howto_release.html">Guide for doing a Clawpack release</a></li>
<li class="toctree-l1"><a class="reference internal" href="regression.html">Regression testing</a></li>
<li class="toctree-l1"><a class="reference internal" href="git_versions.html">Keeping track of repository versions with Git</a></li>
</ul>
</div>
<nav class="contents" id="contents">
<p class="topic-title">Contents</p>
<ul class="simple">
<li><p><a class="reference internal" href="#developers-guide" id="id1">Developers’ Guide</a></p>
<ul>
<li><p><a class="reference internal" href="#guidelines-for-contributing" id="id2">Guidelines for contributing</a></p>
<ul>
<li><p><a class="reference internal" href="#reporting-and-fixing-bugs" id="id3">Reporting and fixing bugs</a></p></li>
<li><p><a class="reference internal" href="#developer-communication" id="id4">Developer communication</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#installation-instructions-for-developers" id="id5">Installation instructions for developers</a></p>
<ul>
<li><p><a class="reference internal" href="#cloning-the-most-recent-code-from-github" id="id6">Cloning the most recent code from Github</a></p></li>
<li><p><a class="reference internal" href="#checking-out-the-master-branch-on-each-repository" id="id7">Checking out the master branch on each repository</a></p></li>
<li><p><a class="reference internal" href="#updating-to-the-latest-master-branch" id="id8">Updating to the latest master branch</a></p></li>
<li><p><a class="reference internal" href="#never-commit-to-master" id="id9">Never commit to <cite>master</cite></a></p></li>
<li><p><a class="reference internal" href="#adding-your-fork-as-a-remote" id="id10">Adding your fork as a remote</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#modifying-code" id="id11">Modifying code</a></p>
<ul>
<li><p><a class="reference internal" href="#issuing-a-pull-request" id="id12">Issuing a pull request</a></p></li>
<li><p><a class="reference internal" href="#testing-a-pull-request" id="id13">Testing a pull request</a></p></li>
<li><p><a class="reference internal" href="#top-level-pull-requests" id="id14">Top-level pull requests</a></p></li>
<li><p><a class="reference internal" href="#git-workflow" id="id15">Git workflow</a></p></li>
</ul>
</li>
<li><p><a class="reference internal" href="#catching-errors-with-pyflakes-and-pylint" id="id16">Catching errors with Pyflakes and Pylint</a></p></li>
<li><p><a class="reference internal" href="#checking-test-coverage" id="id17">Checking test coverage</a></p></li>
<li><p><a class="reference internal" href="#trouble-shooting-tips" id="id18">Trouble-Shooting Tips</a></p></li>
</ul>
</li>
</ul>
</nav>
<section id="guidelines-for-contributing">
<h2><a class="toc-backref" href="#id2" role="doc-backlink">Guidelines for contributing</a><a class="headerlink" href="#guidelines-for-contributing" title="Permalink to this heading">¶</a></h2>
<p>When preparing contributions, please follow the guidelines in
<span class="xref std std-ref">contribution</span>. Also:</p>
<blockquote>
<div><ul class="simple">
<li><p>If the planned changes are substantial or will be backward-incompatible,
it’s best to discuss them on the <a class="reference external" href="http://groups.google.com/group/claw-dev">claw-dev Google group</a> before starting.</p></li>
<li><p>Make sure all tests pass and all the built-in examples run correctly.</p></li>
<li><p>Be verbose and detailed in your commit messages and your pull request.</p></li>
<li><p>It may be wise to have one of the maintainers look at your changes before
they are complete
(especially if the changes will necessitate modifications of tests
and/or examples).</p></li>
<li><p>If your changes are not backward-compatible, your pull request should
include instructions for users to update their own application codes.</p></li>
</ul>
</div></blockquote>
<section id="reporting-and-fixing-bugs">
<h3><a class="toc-backref" href="#id3" role="doc-backlink">Reporting and fixing bugs</a><a class="headerlink" href="#reporting-and-fixing-bugs" title="Permalink to this heading">¶</a></h3>
<p>If you find a bug, post an issue with as much explanation as possible on the
appropriate issue tracker (for instance, the PyClaw issue tracker is at
<a class="reference external" href="https://github.com/clawpack/pyclaw/issues">https://github.com/clawpack/pyclaw/issues</a>. If you’re looking
for something useful to do, try tackling one of the issues listed there.</p>
</section>
<section id="developer-communication">
<h3><a class="toc-backref" href="#id4" role="doc-backlink">Developer communication</a><a class="headerlink" href="#developer-communication" title="Permalink to this heading">¶</a></h3>
<p>Developer communication takes place on the google group at
<a class="reference external" href="http://groups.google.com/group/claw-dev/">http://groups.google.com/group/claw-dev/</a>, and (increasingly) within the issue
trackers on Github.</p>
</section>
</section>
<section id="installation-instructions-for-developers">
<span id="setup-dev"></span><h2><a class="toc-backref" href="#id5" role="doc-backlink">Installation instructions for developers</a><a class="headerlink" href="#installation-instructions-for-developers" title="Permalink to this heading">¶</a></h2>
<section id="cloning-the-most-recent-code-from-github">
<h3><a class="toc-backref" href="#id6" role="doc-backlink">Cloning the most recent code from Github</a><a class="headerlink" href="#cloning-the-most-recent-code-from-github" title="Permalink to this heading">¶</a></h3>
<p>You can create a read-only development version of Clawpack via:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">clawpack</span><span class="o">/</span><span class="n">clawpack</span><span class="o">.</span><span class="n">git</span>
<span class="n">cd</span> <span class="n">clawpack</span>
<span class="n">git</span> <span class="n">submodule</span> <span class="n">init</span>
<span class="n">git</span> <span class="n">submodule</span> <span class="n">update</span>
</pre></div>
</div>
<p><strong>Note:</strong> The <cite>https://github.com…</cite> form of specifying a remote
clones the repository in a form that does not allow pushing to it
(unlike the <cite>git@github.com:…</cite> form). This is good practice, so
you do not accidently try to push to the main clawpack repository
rather than to your own fork (see <a class="reference internal" href="#dev-remote"><span class="std std-ref">Adding your fork as a remote</span></a> below if you
need your own fork, e.g. for issuing pull requests).</p>
<p>The commands above download the following clawpack modules as subrepositories
checked out at specific commits (as opposed to the tip of a branch).</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/clawpack/pyclaw">https://github.com/clawpack/pyclaw</a> (Python code, some of which is
needed also for Fortran version)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/clawutil">https://github.com/clawpack/clawutil</a> (Utility functions,
Makefile.common used in multiple repositories)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/classic">https://github.com/clawpack/classic</a> (Classic single-grid code)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/amrclaw">https://github.com/clawpack/amrclaw</a> (AMR version of Fortran code)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/riemann">https://github.com/clawpack/riemann</a> (Riemann solvers)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/visclaw">https://github.com/clawpack/visclaw</a> (Python graphics and
visualization tools)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/geoclaw">https://github.com/clawpack/geoclaw</a> (GeoClaw)</p></li>
</ul>
<p>This should give a snapshot of the repositories that work well together.
(Note that there are many inter-dependencies between code in the
repositories and checking out a different commit in one repository may break
things in a different repository.)</p>
<p>Before proceeding, it is necessary to make sure you have a few
other packages installed that are now listed in <cite>$CLAW/requirements-dev.txt</cite>
(currently on the master branch and to appear in v5.10.0):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">-</span><span class="n">r</span> <span class="n">requirements</span><span class="o">-</span><span class="n">dev</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
<p>Now install this version of Clawpack using:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">build</span><span class="o">-</span><span class="n">isolation</span> <span class="o">-</span><span class="n">e</span> <span class="o">./</span>
</pre></div>
</div>
<p>The <cite>-e</cite> flag means that this is an editabl version of the Clawpack code
(rather than installing the original version in the <cite>site-packages</cite>
directory).</p>
<p>If you want to use the Fortran versions in <cite>classic</cite>, <cite>amrclaw</cite>, <cite>geoclaw</cite>,
etc., you need to set environment variables and proceed as described at
<a class="reference internal" href="setenv.html#setenv"><span class="std std-ref">Set environment variables</span></a>.</p>
</section>
<section id="checking-out-the-master-branch-on-each-repository">
<h3><a class="toc-backref" href="#id7" role="doc-backlink">Checking out the master branch on each repository</a><a class="headerlink" href="#checking-out-the-master-branch-on-each-repository" title="Permalink to this heading">¶</a></h3>
<p>Following the instructions above gives you a top level <cite>$CLAW</cite> directory
that is checked out to the tip of the master branch, and each subrepository
will be checked out to a particular commit as specified by this master
branch. For development work, You probably want to check out each
subrepository to the master branch as well. The shell script
<cite>$CLAW/pull_all.sh</cite> can be used to do this for all subrepositories (or look
at this file to see how to do it more selectively). At a shell prompt,
type:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">source</span> <span class="n">pull_all</span><span class="o">.</span><span class="n">sh</span>
</pre></div>
</div>
<p>which will check out master on each repository and then do a <cite>git pull</cite> to
make sure it is up to date. If you do this shortly after cloning all the
repositories, they should all have been up to date already.</p>
</section>
<section id="updating-to-the-latest-master-branch">
<h3><a class="toc-backref" href="#id8" role="doc-backlink">Updating to the latest master branch</a><a class="headerlink" href="#updating-to-the-latest-master-branch" title="Permalink to this heading">¶</a></h3>
<p>The script <cite>pull_all.sh</cite> can be used at any time to check out all
subrepositories to master and do a <cite>git pull</cite>. This is handy if you want to
make sure your version of <cite>master</cite> is up to date in every repository.</p>
<p>You should first make sure that you do not have uncommitted changes in any
repository that might conflict with the <cite>git checkout master</cite> or
<cite>git pull</cite> commands. You can do this easily with the command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>python $CLAW/clawutil/src/python/clawutil/claw_git_status.py
</pre></div>
</div>
<p>and then check the files <cite>claw_git_status.txt</cite> and <cite>claw_git_diffs.txt</cite>,
which summarize the status of each subrepository.</p>
</section>
<section id="never-commit-to-master">
<h3><a class="toc-backref" href="#id9" role="doc-backlink">Never commit to <cite>master</cite></a><a class="headerlink" href="#never-commit-to-master" title="Permalink to this heading">¶</a></h3>
<p>You should never commit to <cite>master</cite>, only to a feature branch, so
the <cite>master</cite> branch should always reflect what’s in the <cite>master</cite> branch on
the primary Github repositories.</p>
<p>You can update <cite>master</cite> to reflect any changes via the above approach (for
all subrepositories at once), or do <cite>git checkout master</cite> and then <cite>git
pull</cite> within any of the subrepositories separately.</p>
</section>
<section id="adding-your-fork-as-a-remote">
<span id="dev-remote"></span><h3><a class="toc-backref" href="#id10" role="doc-backlink">Adding your fork as a remote</a><a class="headerlink" href="#adding-your-fork-as-a-remote" title="Permalink to this heading">¶</a></h3>
<p>If you plan to make changes and issue pull requests to one or more
repositories, you will need to do the following steps for each such
repository:</p>
<ol class="arabic">
<li><p>Go to <a class="reference external" href="http://github.com/clawpack">http://github.com/clawpack</a> and fork the repository to your own
Github account. (Click on the repository name and then the <em>Fork</em> button
at the top of the screen.)</p></li>
<li><p>Add a <em>remote</em> pointing to your repository. For example, if you have
forked the <cite>amrclaw</cite> repository to account <cite>username</cite>, you would do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">amrclaw</span>
<span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">username</span> <span class="n">git</span><span class="nd">@github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">username</span><span class="o">/</span><span class="n">amrclaw</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>provided you have ssh keys set up, or else:</p>
<blockquote>
<div><p>git remote add username <a class="reference external" href="https://github.com/username/amrclaw.git">https://github.com/username/amrclaw.git</a></p>
</div></blockquote>
<p>if you don’t mind having to type your password whenever you push or pull.</p>
<p>You should push only to this remote, not to <cite>origin</cite>, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">push</span> <span class="n">username</span>
</pre></div>
</div>
</li>
</ol>
<p>You might also want to clone some or all of the following repositories:</p>
<ul class="simple">
<li><p><a class="reference external" href="https://github.com/clawpack/doc">https://github.com/clawpack/doc</a> (documentation)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/apps">https://github.com/clawpack/apps</a> (To collect applications)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/regression">https://github.com/clawpack/regression</a> (Regression tests)</p></li>
<li><p><a class="reference external" href="https://github.com/clawpack/clawpack-4.x">https://github.com/clawpack/clawpack-4.x</a> (Previous versions, 4.6)</p></li>
</ul>
<p>These are not brought over by cloning the top <cite>clawpack</cite> super-repository.
You can get one of these in read-only mode by doing, e.g.:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">clone</span> <span class="n">https</span><span class="p">:</span><span class="o">//</span><span class="n">github</span><span class="o">.</span><span class="n">com</span><span class="o">/</span><span class="n">clawpack</span><span class="o">/</span><span class="n">doc</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>Then go through the above steps to add your own fork as a remote
if you plan to modify code and issue pull requests.</p>
<p><strong>Note:</strong> The <cite>https://github.com…</cite> form of specifying a remote
clones the repository in a form that does not allow pushing to it
(unlike the <cite>git@github.com:…</cite> form). This is good practice, so
you do not accidently try to push to the main clawpack repository
rather than to your own fork.</p>
</section>
</section>
<section id="modifying-code">
<h2><a class="toc-backref" href="#id11" role="doc-backlink">Modifying code</a><a class="headerlink" href="#modifying-code" title="Permalink to this heading">¶</a></h2>
<p>Before making changes, make sure <em>master</em> is up to date:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
<span class="n">git</span> <span class="n">pull</span>
</pre></div>
</div>
<p>Then create a new branch based on <cite>master</cite> for any new commits:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">new_feature</span> <span class="n">master</span>
</pre></div>
</div>
<p>Now make changes, add and commit them,
and then push to your own fork:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># make some changes</span>
<span class="c1"># git add the modified files</span>
<span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span> <span class="s2">"describe the changes"</span>
<span class="n">git</span> <span class="n">push</span> <span class="n">username</span> <span class="n">new_feature</span>
</pre></div>
</div>
<p>If you want these changes pulled into <em>master</em>,
you can issue a pull request from the github page for your fork of this
repository (make sure to select the correct branch of your repository).</p>
<p><strong>Note:</strong> If you accidentally commit to <cite>master</cite> rather than creating a
feature branch first, you can easily recover:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">new_feature</span>
</pre></div>
</div>
<p>will create a new branch based on the current state and history (including
your commits to <cite>master</cite>) and you can just continue adding additional
commits.</p>
<p>The only problem is your <cite>master</cite> branch no longer agrees with the history
on Github and you want to throw away the commits you made to <cite>master</cite>. The
easiest way to do this is just to make sure you’re on a different branch,
e.g.,</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">new_feature</span>
</pre></div>
</div>
<p>and then:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">branch</span> <span class="o">-</span><span class="n">D</span> <span class="n">master</span>
<span class="n">git</span> <span class="n">checkout</span> <span class="o">-</span><span class="n">b</span> <span class="n">master</span> <span class="n">origin</span><span class="o">/</span><span class="n">master</span>
</pre></div>
</div>
<p>This deletes your local branch named <cite>master</cite> and recreates a branch with
the same name based on <cite>origin/master</cite>, which is what you want.</p>
<section id="issuing-a-pull-request">
<span id="developers-pr"></span><h3><a class="toc-backref" href="#id12" role="doc-backlink">Issuing a pull request</a><a class="headerlink" href="#issuing-a-pull-request" title="Permalink to this heading">¶</a></h3>
<p>Before issuing a pull request, you should make sure you have not broken
anything:</p>
<ol class="arabic">
<li><p>Make sure you are up to date with <em>master</em>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
<span class="n">git</span> <span class="n">pull</span>
</pre></div>
</div>
<p>If this does not say “Already up-to-date” then you might want to rebase
your modified code onto the updated master. With your feature branch
checked out, you can see what newer commits have been added to <em>master</em>
via:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">new_feature</span>
<span class="n">git</span> <span class="n">log</span> <span class="n">HEAD</span><span class="o">..</span><span class="n">master</span>
</pre></div>
</div>
<p>If your new feature can be added on to the updated master, you can rebase:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">rebase</span> <span class="n">master</span>
</pre></div>
</div>
<p>which gives a cleaner history than merging the branches.</p>
</li>
<li><p>Run the appropriate regression tests. If you have modified code
in pyclaw or riemann, then you should run the pyclaw tests. First,
if you have modified any Fortran code, you need to recompile:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">clawpack</span><span class="o">/</span>
<span class="n">pip</span> <span class="n">install</span> <span class="o">--</span><span class="n">user</span> <span class="o">--</span><span class="n">no</span><span class="o">-</span><span class="n">build</span><span class="o">-</span><span class="n">isolation</span> <span class="o">-</span><span class="n">e</span> <span class="o">./</span>
</pre></div>
</div>
<p>Then run the tests:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">pyclaw</span>
<span class="n">nosetests</span>
</pre></div>
</div>
<p>If any tests fail, you should fix them before issuing a pull request.</p>
</li>
</ol>
<p>To issue a pull request (PR), go to the Github page for your fork of the
repository in question, select the branch from which you want the pull
request to originate, and then click the <em>Pull Request</em> button.</p>
</section>
<section id="testing-a-pull-request">
<span id="test-pr"></span><h3><a class="toc-backref" href="#id13" role="doc-backlink">Testing a pull request</a><a class="headerlink" href="#testing-a-pull-request" title="Permalink to this heading">¶</a></h3>
<p>To test out someone else’s pull request, follow these instructions:
For
example, if you want to try out a pull request coming from a branch named
<em>bug-fix</em> from user <em>rjleveque</em> to the <em>master</em> branch of
the <em>amrclaw</em> repository, you would do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>cd $CLAW/amrclaw # (and make sure you don't have uncommitted changes)
git checkout master
git pull # to make sure you are up to date
git checkout -b rjleveque-bug-fix master
git pull https://github.com/rjleveque/amrclaw.git bug-fix
</pre></div>
</div>
<p>This puts you on a new branch of your own repository named
<em>rjleveque-bug-fix</em> that has the proposed changes pulled into it.</p>
<p>Once you are done testing, you can get rid of this branch via:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">checkout</span> <span class="n">master</span>
<span class="n">git</span> <span class="n">branch</span> <span class="o">-</span><span class="n">D</span> <span class="n">rjleveque</span><span class="o">-</span><span class="n">bug</span><span class="o">-</span><span class="n">fix</span>
</pre></div>
</div>
</section>
<section id="top-level-pull-requests">
<span id="toplevel-pr"></span><h3><a class="toc-backref" href="#id14" role="doc-backlink">Top-level pull requests</a><a class="headerlink" href="#top-level-pull-requests" title="Permalink to this heading">¶</a></h3>
<p>The top level <em>clawpack</em> repository keeps track of what versions of the
subrepositories work well together.</p>
<p>If you make pull requests in two different repositories that are linked, say
to both <em>pyclaw</em> and <em>riemann</em>, then you should also push these changes to
the top-level <em>clawpack</em> repository and issue a PR for this change:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>cd $CLAW # top-level clawpack repository
git checkout master
git pull
git checkout -b pyclaw-riemann-changes
git add pyclaw riemann
git commit -m "Cross-update pyclaw and riemann."
git push username pyclaw-riemann-changes
</pre></div>
</div>
</section>
<section id="git-workflow">
<h3><a class="toc-backref" href="#id15" role="doc-backlink">Git workflow</a><a class="headerlink" href="#git-workflow" title="Permalink to this heading">¶</a></h3>
<p>See <span class="xref std std-ref">git-resources</span> for useful links.</p>
</section>
</section>
<section id="catching-errors-with-pyflakes-and-pylint">
<h2><a class="toc-backref" href="#id16" role="doc-backlink">Catching errors with Pyflakes and Pylint</a><a class="headerlink" href="#catching-errors-with-pyflakes-and-pylint" title="Permalink to this heading">¶</a></h2>
<p>Pyflakes and Pylint are Python packages designed to help you catch errors or
poor coding practices. To run pylint on the whole PyClaw package, do:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>cd $PYCLAW
pylint -d C pyclaw
</pre></div>
</div>
<p>The <cite>-d</cite> option suppresses a lot of style warnings, since PyClaw doesn’t
generally conform to PEP8. To run pylint on just one module, use something
like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pylint</span> <span class="o">-</span><span class="n">d</span> <span class="n">C</span> <span class="n">pyclaw</span><span class="o">.</span><span class="n">state</span>
</pre></div>
</div>
<p>Since pylint output can be long, it’s helpful to write it to an html file
and open that in a web browser:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pylint</span> <span class="o">-</span><span class="n">d</span> <span class="n">C</span> <span class="n">pyclaw</span><span class="o">.</span><span class="n">state</span> <span class="o">-</span><span class="n">f</span> <span class="n">html</span> <span class="o">></span> <span class="n">pylint</span><span class="o">.</span><span class="n">html</span>
</pre></div>
</div>
<p>Pyflakes is similar to pylint but aims only to catch errors. If you
use Vim, there is a nice extension package
<a class="reference external" href="https://github.com/kevinw/pyflakes-vim">pyflakes.vim</a>
that will catch errors as you code and underline them in red.</p>
</section>
<section id="checking-test-coverage">
<h2><a class="toc-backref" href="#id17" role="doc-backlink">Checking test coverage</a><a class="headerlink" href="#checking-test-coverage" title="Permalink to this heading">¶</a></h2>
<p>You can use nose to see how much of the code is covered by the current
suite of tests and track progress if you add more tests</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">nosetests</span> <span class="o">--</span><span class="k">with</span><span class="o">-</span><span class="n">coverage</span> <span class="o">--</span><span class="n">cover</span><span class="o">-</span><span class="n">package</span><span class="o">=</span><span class="n">pyclaw</span> <span class="o">--</span><span class="n">cover</span><span class="o">-</span><span class="n">html</span>
</pre></div>
</div>
<p>This creates a set of html files in <cite>./cover</cite>, showing exactly which lines
of code have been tested.</p>
</section>
<section id="trouble-shooting-tips">
<h2><a class="toc-backref" href="#id18" role="doc-backlink">Trouble-Shooting Tips</a><a class="headerlink" href="#trouble-shooting-tips" title="Permalink to this heading">¶</a></h2>
<p>If you are having trouble installing or building Clawpack try out some of the
following tips:</p>
<blockquote>
<div><ul class="simple">
<li><p>Check to see if you have set the environment variable <cite>FFLAGS</cite> which may be
overriding flags that need to be set. This is especially important to check
when building the PyClaw fortran libraries as a number of flags must be set
for the Python bindings and will override the defaults.</p></li>
</ul>
</div></blockquote>
</section>
</section>
<div class="clearer"></div>
</div>
</div>
</div>
<div class="sphinxsidebar" role="navigation" aria-label="main navigation">
<div class="sphinxsidebarwrapper">
<p><a href="http://clawpack.org/">
<img class="logo" src= "_static/clawlogo.jpg" alt="Logo"/>
</a>
<h2>Version 5.11.x</h2>
</p>
<div>
<h3><a href="contents.html">Table of Contents</a></h3>
<ul>
<li><a class="reference internal" href="#">Developers’ Guide</a><ul>
<li><a class="reference internal" href="#guidelines-for-contributing">Guidelines for contributing</a><ul>
<li><a class="reference internal" href="#reporting-and-fixing-bugs">Reporting and fixing bugs</a></li>
<li><a class="reference internal" href="#developer-communication">Developer communication</a></li>
</ul>
</li>
<li><a class="reference internal" href="#installation-instructions-for-developers">Installation instructions for developers</a><ul>
<li><a class="reference internal" href="#cloning-the-most-recent-code-from-github">Cloning the most recent code from Github</a></li>
<li><a class="reference internal" href="#checking-out-the-master-branch-on-each-repository">Checking out the master branch on each repository</a></li>
<li><a class="reference internal" href="#updating-to-the-latest-master-branch">Updating to the latest master branch</a></li>
<li><a class="reference internal" href="#never-commit-to-master">Never commit to <cite>master</cite></a></li>
<li><a class="reference internal" href="#adding-your-fork-as-a-remote">Adding your fork as a remote</a></li>
</ul>
</li>
<li><a class="reference internal" href="#modifying-code">Modifying code</a><ul>
<li><a class="reference internal" href="#issuing-a-pull-request">Issuing a pull request</a></li>
<li><a class="reference internal" href="#testing-a-pull-request">Testing a pull request</a></li>
<li><a class="reference internal" href="#top-level-pull-requests">Top-level pull requests</a></li>
<li><a class="reference internal" href="#git-workflow">Git workflow</a></li>
</ul>
</li>
<li><a class="reference internal" href="#catching-errors-with-pyflakes-and-pylint">Catching errors with Pyflakes and Pylint</a></li>
<li><a class="reference internal" href="#checking-test-coverage">Checking test coverage</a></li>
<li><a class="reference internal" href="#trouble-shooting-tips">Trouble-Shooting Tips</a></li>
</ul>
</li>
</ul>
</div><h3>Related Topics</h3>
<ul>
<li><a href="contents.html">Documentation overview</a><ul>
<li><a href="pyclaw/index.html">PyClaw</a><ul>
<li>Previous: <a href="pyclaw/classes.html" title="previous chapter">Understanding Pyclaw Classes</a></li>
<li>Next: <a href="howto_doc.html" title="next chapter">Guide for updating this documentation</a></li>
</ul></li>
</ul></li>
</ul>
<div class="widget navlinks">
<h3>This Page</h3>
<ul class="this-page-menu">
<li><a href="_sources/developers.rst.txt"
rel="nofollow"
target="_blank">Source .rst</a></li>
<li><a href="https://github.com/clawpack/doc/blob/dev/doc/developers.rst"
rel="nofollow"
target="_blank">Source on GitHub</a></li>
<li><a href="https://github.com/clawpack/doc/commits/dev/doc/developers.rst"
rel="nofollow"
target="_blank">History</a></li>
<li><a href="https://github.com/clawpack/doc/edit/dev/doc/developers.rst"
rel="nofollow"
target="_blank">Suggest Edits</a></li>
<li><a href="https://github.com/clawpack/doc/issues/new/choose"
rel="nofollow"
target="_blank">Raise an Issue</a></li>
</ul>
</div>
<div 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>
</div>
<script>document.getElementById('searchbox').style.display = "block"</script>
<h4>Latest Version</h4>
<ul>
<li><a href="./dev/developers.html">dev</a></li>
<li><a href="developers.html">v5.11.x</a></li>
</ul>
<h4>Older Versions</h4>
<ul>
<li><a href="./v5.10.x/developers.html">v5.10.x</a></li>
<li><a href="./v5.7.x/developers.html">v5.7.x</a></li>
<li><a href="./v5.8.x/developers.html">v5.8.x</a></li>
<li><a href="./v5.9.x/developers.html">v5.9.x</a></li>
</ul>
</div>
</div>
<div class="clearer"></div>
</div>
<div class="footer">
© Copyright CC-BY 2024, The Clawpack Development Team.
Created using <a href="http://sphinx.pocoo.org/">Sphinx</a>.
</div>
<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-44811544-1', 'auto');
ga('send', 'pageview');
</script>
</body>
</html>