/
contributing.html
641 lines (564 loc) · 35.2 KB
/
contributing.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
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
<!DOCTYPE html>
<html>
<head>
<meta charset="utf-8" />
<meta name="viewport" content="width=device-width, initial-scale=1.0" />
<title>Contributing to GeoPandas — GeoPandas 0.10.0 documentation</title>
<link href="../_static/css/theme.css" rel="stylesheet" />
<link href="../_static/css/index.c5995385ac14fb8791e8eb36b4908be2.css" rel="stylesheet" />
<link rel="stylesheet"
href="../_static/vendor/fontawesome/5.13.0/css/all.min.css">
<link rel="preload" as="font" type="font/woff2" crossorigin
href="../_static/vendor/fontawesome/5.13.0/webfonts/fa-solid-900.woff2">
<link rel="preload" as="font" type="font/woff2" crossorigin
href="../_static/vendor/fontawesome/5.13.0/webfonts/fa-brands-400.woff2">
<link rel="stylesheet" type="text/css" href="../_static/pygments.css" />
<link rel="stylesheet" type="text/css" href="../_static/basic.css" />
<link rel="stylesheet" type="text/css" href="../_static/plot_directive.css" />
<link rel="stylesheet" type="text/css" href="../_static/custom.css" />
<link rel="stylesheet" type="text/css" href="../_static/gallery.css" />
<link rel="preload" as="script" href="../_static/js/index.1c5a1a01449ed65a7b51.js">
<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/doctools.js"></script>
<script src="../_static/toggleprompt.js"></script>
<script crossorigin="anonymous" integrity="sha256-Ae2Vz/4ePdIu6ZyI/5ZGsYnb+m0JlOmKPjt6XZ9JJkA=" src="https://cdnjs.cloudflare.com/ajax/libs/require.js/2.3.4/require.min.js"></script>
<link rel="shortcut icon" href="../_static/favicon.png"/>
<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="GeoPandas Project Code of Conduct" href="code_of_conduct.html" />
<link rel="prev" title="Community" href="../community.html" />
<meta name="viewport" content="width=device-width, initial-scale=1" />
<meta name="docsearch:language" content="en" />
</head>
<body data-spy="scroll" data-target="#bd-toc-nav" data-offset="80">
<div class="container-fluid" id="banner"></div>
<nav class="navbar navbar-light navbar-expand-lg bg-light fixed-top bd-navbar" id="navbar-main"><div class="container-xl">
<div id="navbar-start">
<a class="navbar-brand" href="../index.html">
<img src="../_static/geopandas_logo_web.svg" class="logo" alt="logo">
</a>
</div>
<button class="navbar-toggler" type="button" data-toggle="collapse" data-target="#navbar-collapsible" aria-controls="navbar-collapsible" aria-expanded="false" aria-label="Toggle navigation">
<span class="navbar-toggler-icon"></span>
</button>
<div id="navbar-collapsible" class="col-lg-9 collapse navbar-collapse">
<div id="navbar-center" class="mr-auto">
<div class="navbar-center-item">
<ul id="navbar-main-elements" class="navbar-nav">
<li class="toctree-l1 nav-item">
<a class="reference internal nav-link" href="../index.html">
Home
</a>
</li>
<li class="toctree-l1 nav-item">
<a class="reference internal nav-link" href="../about.html">
About
</a>
</li>
<li class="toctree-l1 nav-item">
<a class="reference internal nav-link" href="../getting_started.html">
Getting started
</a>
</li>
<li class="toctree-l1 nav-item">
<a class="reference internal nav-link" href="../docs.html">
Documentation
</a>
</li>
<li class="toctree-l1 current active nav-item">
<a class="reference internal nav-link" href="../community.html">
Community
</a>
</li>
</ul>
</div>
</div>
<div id="navbar-end">
<div class="navbar-end-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/geopandas/geopandas" rel="noopener" target="_blank" title="GitHub">
<span><i class="fab fa-github-square"></i></span>
<label class="sr-only">GitHub</label>
</a>
</li>
<li class="nav-item">
<a class="nav-link" href="https://twitter.com/geopandas" rel="noopener" target="_blank" title="Twitter">
<span><i class="fab fa-twitter-square"></i></span>
<label class="sr-only">Twitter</label>
</a>
</li>
</ul>
</div>
</div>
</div>
</div>
</nav>
<div class="container-xl">
<div class="row">
<!-- Only show if we have sidebars configured, else just a small margin -->
<div class="col-12 col-md-3 bd-sidebar"><form class="bd-search d-flex align-items-center" action="../search.html" method="get">
<i class="icon fas fa-search"></i>
<input type="search" class="form-control" name="q" id="search-input" placeholder="Search the docs ..." aria-label="Search the docs ..." autocomplete="off" >
</form><nav class="bd-links" id="bd-docs-nav" aria-label="Main navigation">
<div class="bd-toc-item active">
<p class="caption" role="heading">
<span class="caption-text">
Community
</span>
</p>
<ul class="current nav bd-sidenav">
<li class="toctree-l1 current active">
<a class="current reference internal" href="#">
Contributing
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="code_of_conduct.html">
Code of Conduct
</a>
</li>
<li class="toctree-l1">
<a class="reference internal" href="ecosystem.html">
Ecosystem
</a>
</li>
</ul>
</div>
</nav>
</div>
<div class="d-none d-xl-block col-xl-2 bd-toc">
<div class="toc-item">
<div class="tocsection onthispage pt-5 pb-3">
<i class="fas fa-list"></i> On this page
</div>
<nav id="bd-toc-nav">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#overview">
Overview
</a>
<ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry">
<a class="reference internal nav-link" href="#seven-steps-for-contributing">
Seven Steps for Contributing
</a>
</li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#forking-the-geopandas-repository-using-git">
1) Forking the
<em>
GeoPandas
</em>
repository using Git
</a>
<ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry">
<a class="reference internal nav-link" href="#getting-started-with-git">
Getting started with Git
</a>
</li>
<li class="toc-h3 nav-item toc-entry">
<a class="reference internal nav-link" href="#forking">
Forking
</a>
</li>
<li class="toc-h3 nav-item toc-entry">
<a class="reference internal nav-link" href="#creating-a-branch">
Creating a branch
</a>
</li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#creating-a-development-environment">
2) Creating a development environment
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#installing-dependencies">
3) Installing Dependencies
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#making-a-development-build">
4) Making a development build
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#making-changes-and-writing-tests">
5) Making changes and writing tests
</a>
<ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry">
<a class="reference internal nav-link" href="#writing-tests">
Writing tests
</a>
</li>
<li class="toc-h3 nav-item toc-entry">
<a class="reference internal nav-link" href="#running-the-test-suite">
Running the test suite
</a>
</li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#updating-the-documentation">
6) Updating the Documentation
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#submitting-a-pull-request">
7) Submitting a Pull Request
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#style-guide-linting">
Style Guide & Linting
</a>
</li>
<li class="toc-h2 nav-item toc-entry">
<a class="reference internal nav-link" href="#commit-message-conventions">
Commit message conventions
</a>
</li>
</ul>
</nav>
</div>
<div class="toc-item">
</div>
</div>
<main class="col-12 col-md-9 col-xl-7 py-md-5 pl-md-5 pr-md-4 bd-content" role="main">
<div>
<div class="section" id="contributing-to-geopandas">
<h1>Contributing to GeoPandas<a class="headerlink" href="#contributing-to-geopandas" title="Permalink to this headline">¶</a></h1>
<p>(Contribution guidelines largely copied from <a class="reference external" href="http://pandas.pydata.org/pandas-docs/stable/contributing.html">pandas</a>)</p>
<div class="section" id="overview">
<h2>Overview<a class="headerlink" href="#overview" title="Permalink to this headline">¶</a></h2>
<p>Contributions to GeoPandas are very welcome. They are likely to
be accepted more quickly if they follow these guidelines.</p>
<p>At this stage of GeoPandas development, the priorities are to define a
simple, usable, and stable API and to have clean, maintainable,
readable code. Performance matters, but not at the expense of those
goals.</p>
<p>In general, GeoPandas follows the conventions of the pandas project
where applicable.</p>
<p>In particular, when submitting a pull request:</p>
<ul class="simple">
<li><p>All existing tests should pass. Please make sure that the test
suite passes, both locally and on
<a class="reference external" href="hhttps://github.com/geopandas/geopandas/actions">GitHub Actions</a>. Status on
GHA will be visible on a pull request. GHA are automatically enabled
on your own fork as well. To trigger a check, make a PR to your own fork.</p></li>
<li><p>New functionality should include tests. Please write reasonable
tests for your code and make sure that they pass on your pull request.</p></li>
<li><p>Classes, methods, functions, etc. should have docstrings. The first
line of a docstring should be a standalone summary. Parameters and
return values should be documented explicitly.</p></li>
<li><p>Follow PEP 8 when possible. We use <a class="reference external" href="https://black.readthedocs.io/en/stable/">Black</a> and <a class="reference external" href="http://flake8.pycqa.org/en/latest/">Flake8</a> to ensure a consistent code
format throughout the project. For more details see
<a class="reference internal" href="#contributing-style"><span class="std std-ref">below</span></a>.</p></li>
<li><p>Imports should be grouped with standard library imports first,
3rd-party libraries next, and GeoPandas imports third. Within each
grouping, imports should be alphabetized. Always use absolute
imports when possible, and explicit relative imports for local
imports when necessary in tests.</p></li>
<li><p>GeoPandas supports Python 3.7+ only. The last version of GeoPandas
supporting Python 2 is 0.6.</p></li>
</ul>
<div class="section" id="seven-steps-for-contributing">
<h3>Seven Steps for Contributing<a class="headerlink" href="#seven-steps-for-contributing" title="Permalink to this headline">¶</a></h3>
<p>There are seven basic steps to contributing to <em>GeoPandas</em>:</p>
<ol class="arabic simple">
<li><p>Fork the <em>GeoPandas</em> git repository</p></li>
<li><p>Create a development environment</p></li>
<li><p>Install <em>GeoPandas</em> dependencies</p></li>
<li><p>Make a <code class="docutils literal notranslate"><span class="pre">development</span></code> build of <em>GeoPandas</em></p></li>
<li><p>Make changes to code and add tests</p></li>
<li><p>Update the documentation</p></li>
<li><p>Submit a Pull Request</p></li>
</ol>
<p>Each of these 7 steps is detailed below.</p>
</div>
</div>
<div class="section" id="forking-the-geopandas-repository-using-git">
<h2>1) Forking the <em>GeoPandas</em> repository using Git<a class="headerlink" href="#forking-the-geopandas-repository-using-git" title="Permalink to this headline">¶</a></h2>
<p>To the new user, working with Git is one of the more daunting aspects of contributing to <em>GeoPandas*</em>.
It can very quickly become overwhelming, but sticking to the guidelines below will help keep the process
straightforward and mostly trouble free. As always, if you are having difficulties please
feel free to ask for help.</p>
<p>The code is hosted on <a class="reference external" href="https://github.com/geopandas/geopandas">GitHub</a>. To
contribute you will need to sign up for a <a class="reference external" href="https://github.com/signup/free">free GitHub account</a>. We use <a class="reference external" href="http://git-scm.com/">Git</a> for
version control to allow many people to work together on the project.</p>
<p>Some great resources for learning Git:</p>
<ul class="simple">
<li><p>Software Carpentry’s <a class="reference external" href="http://swcarpentry.github.io/git-novice/">Git Tutorial</a></p></li>
<li><p><a class="reference external" href="https://www.atlassian.com/git/tutorials/what-is-version-control">Atlassian</a></p></li>
<li><p>the <a class="reference external" href="http://help.github.com/">GitHub help pages</a>.</p></li>
<li><p>Matthew Brett’s <a class="reference external" href="http://matthew-brett.github.com/pydagogue/">Pydagogue</a>.</p></li>
</ul>
<div class="section" id="getting-started-with-git">
<h3>Getting started with Git<a class="headerlink" href="#getting-started-with-git" title="Permalink to this headline">¶</a></h3>
<p><a class="reference external" href="http://help.github.com/set-up-git-redirect">GitHub has instructions</a> for installing git,
setting up your SSH key, and configuring git. All these steps need to be completed before
you can work seamlessly between your local repository and GitHub.</p>
</div>
<div class="section" id="forking">
<span id="contributing-forking"></span><h3>Forking<a class="headerlink" href="#forking" title="Permalink to this headline">¶</a></h3>
<p>You will need your own fork to work on the code. Go to the <a class="reference external" href="https://github.com/geopandas/geopandas">GeoPandas project
page</a> and hit the <code class="docutils literal notranslate"><span class="pre">Fork</span></code> button. You will
want to clone your fork to your machine:</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">git</span><span class="nd">@github</span><span class="o">.</span><span class="n">com</span><span class="p">:</span><span class="n">your</span><span class="o">-</span><span class="n">user</span><span class="o">-</span><span class="n">name</span><span class="o">/</span><span class="n">geopandas</span><span class="o">.</span><span class="n">git</span> <span class="n">geopandas</span><span class="o">-</span><span class="n">yourname</span>
<span class="n">cd</span> <span class="n">geopandas</span><span class="o">-</span><span class="n">yourname</span>
<span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</span> <span class="n">git</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">geopandas</span><span class="o">/</span><span class="n">geopandas</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<p>This creates the directory <cite>geopandas-yourname</cite> and connects your repository to
the upstream (main project) <em>GeoPandas</em> repository.</p>
<p>The testing suite will run automatically on GitHub Actions once your pull request is
submitted. The test suite will also automatically run on your branch so you can
check it prior to submitting the pull request.</p>
</div>
<div class="section" id="creating-a-branch">
<h3>Creating a branch<a class="headerlink" href="#creating-a-branch" title="Permalink to this headline">¶</a></h3>
<p>You want your master branch to reflect only production-ready code, so create a
feature branch for making your changes. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">branch</span> <span class="n">shiny</span><span class="o">-</span><span class="n">new</span><span class="o">-</span><span class="n">feature</span>
<span class="n">git</span> <span class="n">checkout</span> <span class="n">shiny</span><span class="o">-</span><span class="n">new</span><span class="o">-</span><span class="n">feature</span>
</pre></div>
</div>
<p>The above can be simplified to:</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">shiny</span><span class="o">-</span><span class="n">new</span><span class="o">-</span><span class="n">feature</span>
</pre></div>
</div>
<p>This changes your working directory to the shiny-new-feature branch. Keep any
changes in this branch specific to one bug or feature so it is clear
what the branch brings to <em>GeoPandas</em>. You can have many shiny-new-features
and switch in between them using the git checkout command.</p>
<p>To update this branch, you need to retrieve the changes from the master branch:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">fetch</span> <span class="n">upstream</span>
<span class="n">git</span> <span class="n">rebase</span> <span class="n">upstream</span><span class="o">/</span><span class="n">master</span>
</pre></div>
</div>
<p>This will replay your commits on top of the latest GeoPandas git master. If this
leads to merge conflicts, you must resolve these before submitting your pull
request. If you have uncommitted changes, you will need to <code class="docutils literal notranslate"><span class="pre">stash</span></code> them prior
to updating. This will effectively store your changes and they can be reapplied
after updating.</p>
</div>
</div>
<div class="section" id="creating-a-development-environment">
<span id="contributing-dev-env"></span><h2>2) Creating a development environment<a class="headerlink" href="#creating-a-development-environment" title="Permalink to this headline">¶</a></h2>
<p>A development environment is a virtual space where you can keep an independent installation of <em>GeoPandas</em>.
This makes it easy to keep both a stable version of python in one place you use for work, and a development
version (which you may break while playing with code) in another.</p>
<p>An easy way to create a <em>GeoPandas</em> development environment is as follows:</p>
<ul class="simple">
<li><p>Install either <a class="reference external" href="http://docs.continuum.io/anaconda/">Anaconda</a> or
<a class="reference external" href="http://conda.pydata.org/miniconda.html">miniconda</a></p></li>
<li><p>Make sure that you have <a class="reference internal" href="#contributing-forking"><span class="std std-ref">cloned the repository</span></a></p></li>
<li><p><code class="docutils literal notranslate"><span class="pre">cd</span></code> to the <em>geopandas*</em> source directory</p></li>
</ul>
<p>Tell conda to create a new environment, named <code class="docutils literal notranslate"><span class="pre">geopandas_dev</span></code>, or any other name you would like
for this environment, by running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">create</span> <span class="o">-</span><span class="n">n</span> <span class="n">geopandas_dev</span> <span class="n">python</span>
</pre></div>
</div>
<p>This will create the new environment, and not touch any of your existing environments,
nor any existing python installation.</p>
<p>To work in this environment, you need to <code class="docutils literal notranslate"><span class="pre">activate</span></code> it. The instructions below
should work for both Windows, Mac and Linux:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">activate</span> <span class="n">geopandas_dev</span>
</pre></div>
</div>
<p>Once your environment is activated, you will see a confirmation message to
indicate you are in the new development environment.</p>
<p>To view your environments:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">info</span> <span class="o">-</span><span class="n">e</span>
</pre></div>
</div>
<p>To return to you home root environment:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">deactivate</span>
</pre></div>
</div>
<p>See the full conda docs <a class="reference external" href="http://conda.pydata.org/docs">here</a>.</p>
<p>At this point you can easily do a <em>development</em> install, as detailed in the next sections.</p>
</div>
<div class="section" id="installing-dependencies">
<h2>3) Installing Dependencies<a class="headerlink" href="#installing-dependencies" title="Permalink to this headline">¶</a></h2>
<p>To run <em>GeoPandas</em> in an development environment, you must first install
<em>GeoPandas</em>’s dependencies. We suggest doing so using the following commands
(executed after your development environment has been activated):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">conda</span> <span class="n">install</span> <span class="o">-</span><span class="n">c</span> <span class="n">conda</span><span class="o">-</span><span class="n">forge</span> <span class="n">pandas</span> <span class="n">fiona</span> <span class="n">shapely</span> <span class="n">pyproj</span> <span class="n">rtree</span> <span class="n">pytest</span>
</pre></div>
</div>
<p>This should install all necessary dependencies.</p>
</div>
<div class="section" id="making-a-development-build">
<h2>4) Making a development build<a class="headerlink" href="#making-a-development-build" title="Permalink to this headline">¶</a></h2>
<p>Once dependencies are in place, make an in-place build by navigating to the git
clone of the <em>GeoPandas</em> repository and running:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">setup</span><span class="o">.</span><span class="n">py</span> <span class="n">develop</span>
</pre></div>
</div>
</div>
<div class="section" id="making-changes-and-writing-tests">
<h2>5) Making changes and writing tests<a class="headerlink" href="#making-changes-and-writing-tests" title="Permalink to this headline">¶</a></h2>
<p><em>GeoPandas</em> is serious about testing and strongly encourages contributors to embrace
<a class="reference external" href="http://en.wikipedia.org/wiki/Test-driven_development">test-driven development (TDD)</a>.
This development process “relies on the repetition of a very short development cycle:
first the developer writes an (initially failing) automated test case that defines a desired
improvement or new function, then produces the minimum amount of code to pass that test.”
So, before actually writing any code, you should write your tests. Often the test can be
taken from the original GitHub issue. However, it is always worth considering additional
use cases and writing corresponding tests.</p>
<p>Adding tests is one of the most common requests after code is pushed to <em>GeoPandas</em>. Therefore,
it is worth getting in the habit of writing tests ahead of time so this is never an issue.</p>
<p><em>GeoPandas</em> uses the <a class="reference external" href="http://doc.pytest.org/en/latest/">pytest testing system</a> and the convenient
extensions in <a class="reference external" href="http://docs.scipy.org/doc/numpy/reference/routines.testing.html">numpy.testing</a>.</p>
<div class="section" id="writing-tests">
<h3>Writing tests<a class="headerlink" href="#writing-tests" title="Permalink to this headline">¶</a></h3>
<p>All tests should go into the <code class="docutils literal notranslate"><span class="pre">tests</span></code> directory. This folder contains many
current examples of tests, and we suggest looking to these for inspiration.</p>
<p>The <code class="docutils literal notranslate"><span class="pre">.util</span></code> module has some special <code class="docutils literal notranslate"><span class="pre">assert</span></code> functions that
make it easier to make statements about whether GeoSeries or GeoDataFrame
objects are equivalent. The easiest way to verify that your code is correct is to
explicitly construct the result you expect, then compare the actual result to
the expected correct result, using eg the function <code class="docutils literal notranslate"><span class="pre">assert_geoseries_equal</span></code>.</p>
</div>
<div class="section" id="running-the-test-suite">
<h3>Running the test suite<a class="headerlink" href="#running-the-test-suite" title="Permalink to this headline">¶</a></h3>
<p>The tests can then be run directly inside your Git clone (without having to
install <em>GeoPandas</em>) by typing:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pytest</span>
</pre></div>
</div>
</div>
</div>
<div class="section" id="updating-the-documentation">
<h2>6) Updating the Documentation<a class="headerlink" href="#updating-the-documentation" title="Permalink to this headline">¶</a></h2>
<p><em>GeoPandas</em> documentation resides in the <code class="docutils literal notranslate"><span class="pre">doc</span></code> folder. Changes to the docs are made by
modifying the appropriate file in the <code class="docutils literal notranslate"><span class="pre">source</span></code> folder within <code class="docutils literal notranslate"><span class="pre">doc</span></code>. <em>GeoPandas</em> docs use
mixture of reStructuredText syntax for <code class="docutils literal notranslate"><span class="pre">rst</span></code> files, <a class="reference external" href="http://www.sphinx-doc.org/en/stable/rest.html#rst-primer">which is explained here</a> and MyST syntax for <code class="docutils literal notranslate"><span class="pre">md</span></code>
files <a class="reference external" href="https://myst-parser.readthedocs.io/en/latest/index.html">explained here</a>.
The docstrings follow the <a class="reference external" href="https://github.com/numpy/numpy/blob/master/doc/HOWTO_DOCUMENT.rst.txt">Numpy Docstring standard</a>. Some pages
and examples are Jupyter notebooks converted to docs using <a class="reference external" href="https://nbsphinx.readthedocs.io/">nbsphinx</a>. Jupyter notebooks should be stored without the output.</p>
<p>We highly encourage you to follow the <a class="reference external" href="https://developers.google.com/style/highlights">Google developer documentation style guide</a> when updating or creating new documentation.</p>
<p>Once you have made your changes, you may try if they render correctly by
building the docs using sphinx. To do so, you can navigate to the <cite>doc</cite> folder:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">doc</span>
</pre></div>
</div>
<p>and type:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>The resulting html pages will be located in <code class="docutils literal notranslate"><span class="pre">doc/build/html</span></code>.</p>
<p>In case of any errors, you can try to use <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> within a new environment based on
environment.yml specification in the <code class="docutils literal notranslate"><span class="pre">doc</span></code> folder. You may need to register Jupyter kernel as
<code class="docutils literal notranslate"><span class="pre">geopandas_docs</span></code>. Using conda:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">doc</span>
<span class="n">conda</span> <span class="n">env</span> <span class="n">create</span> <span class="o">-</span><span class="n">f</span> <span class="n">environment</span><span class="o">.</span><span class="n">yml</span>
<span class="n">conda</span> <span class="n">activate</span> <span class="n">geopandas_docs</span>
<span class="n">python</span> <span class="o">-</span><span class="n">m</span> <span class="n">ipykernel</span> <span class="n">install</span> <span class="o">--</span><span class="n">user</span> <span class="o">--</span><span class="n">name</span> <span class="n">geopandas_docs</span>
<span class="n">make</span> <span class="n">html</span>
</pre></div>
</div>
<p>For minor updates, you can skip the <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">html</span></code> part as reStructuredText and MyST
syntax are usually quite straightforward.</p>
</div>
<div class="section" id="submitting-a-pull-request">
<h2>7) Submitting a Pull Request<a class="headerlink" href="#submitting-a-pull-request" title="Permalink to this headline">¶</a></h2>
<p>Once you’ve made changes and pushed them to your forked repository, you then
submit a pull request to have them integrated into the <em>GeoPandas</em> code base.</p>
<p>You can find a pull request (or PR) tutorial in the <a class="reference external" href="https://help.github.com/articles/using-pull-requests/">GitHub’s Help Docs</a>.</p>
</div>
<div class="section" id="style-guide-linting">
<span id="contributing-style"></span><h2>Style Guide & Linting<a class="headerlink" href="#style-guide-linting" title="Permalink to this headline">¶</a></h2>
<p>GeoPandas follows the <a class="reference external" href="http://www.python.org/dev/peps/pep-0008/">PEP8</a> standard
and uses <a class="reference external" href="https://black.readthedocs.io/en/stable/">Black</a> and
<a class="reference external" href="http://flake8.pycqa.org/en/latest/">Flake8</a> to ensure a consistent code
format throughout the project.</p>
<p>Continuous Integration (GitHub Actions) will run those tools and
report any stylistic errors in your code. Therefore, it is helpful before
submitting code to run the check yourself:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">black</span> <span class="n">geopandas</span>
<span class="n">git</span> <span class="n">diff</span> <span class="n">upstream</span><span class="o">/</span><span class="n">master</span> <span class="o">-</span><span class="n">u</span> <span class="o">--</span> <span class="s2">"*.py"</span> <span class="o">|</span> <span class="n">flake8</span> <span class="o">--</span><span class="n">diff</span>
</pre></div>
</div>
<p>to auto-format your code. Additionally, many editors have plugins that will
apply <code class="docutils literal notranslate"><span class="pre">black</span></code> as you edit files.</p>
<p>Optionally (but recommended), you can setup <a class="reference external" href="https://pre-commit.com/">pre-commit hooks</a>
to automatically run <code class="docutils literal notranslate"><span class="pre">black</span></code> and <code class="docutils literal notranslate"><span class="pre">flake8</span></code> when you make a git commit. This
can be done by installing <code class="docutils literal notranslate"><span class="pre">pre-commit</span></code>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ python -m pip install pre-commit
</pre></div>
</div>
<p>From the root of the geopandas repository, you should then install the
<code class="docutils literal notranslate"><span class="pre">pre-commit</span></code> included in <em>GeoPandas</em>:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span>$ pre-commit install
</pre></div>
</div>
<p>Then <code class="docutils literal notranslate"><span class="pre">black</span></code> and <code class="docutils literal notranslate"><span class="pre">flake8</span></code> will be run automatically
each time you commit changes. You can skip these checks with
<code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span> <span class="pre">--no-verify</span></code>.</p>
</div>
<div class="section" id="commit-message-conventions">
<h2>Commit message conventions<a class="headerlink" href="#commit-message-conventions" title="Permalink to this headline">¶</a></h2>
<p>Commit your changes to your local repository with an explanatory message. GeoPandas
uses the pandas convention for commit message prefixes and layout. Here are
some common prefixes along with general guidelines for when to use them:</p>
<ul class="simple">
<li><p>ENH: Enhancement, new functionality</p></li>
<li><p>BUG: Bug fix</p></li>
<li><p>DOC: Additions/updates to documentation</p></li>
<li><p>TST: Additions/updates to tests</p></li>
<li><p>BLD: Updates to the build process/scripts</p></li>
<li><p>PERF: Performance improvement</p></li>
<li><p>TYP: Type annotations</p></li>
<li><p>CLN: Code cleanup</p></li>
</ul>
<p>The following defines how a commit message should be structured. Please refer to the
relevant GitHub issues in your commit message using GH1234 or #1234. Either style
is fine, but the former is generally preferred:</p>
<ul class="simple">
<li><p>a subject line with <cite>< 80</cite> chars.</p></li>
<li><p>One blank line.</p></li>
<li><p>Optionally, a commit message body.</p></li>
</ul>
<p>Now you can commit your changes in your local repository:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">commit</span> <span class="o">-</span><span class="n">m</span>
</pre></div>
</div>
</div>
</div>
</div>
<div class='prev-next-bottom'>
<a class='left-prev' id="prev-link" href="../community.html" title="previous page">Community</a>
<a class='right-next' id="next-link" href="code_of_conduct.html" title="next page">GeoPandas Project Code of Conduct</a>
</div>
</main>
</div>
</div>
<script src="../_static/js/index.1c5a1a01449ed65a7b51.js"></script>
<footer class="footer mt-5 mt-md-0">
<div class="container">
<div class="footer-item">
<p class="copyright">
© Copyright 2013–2021, GeoPandas developers.<br/>
</p>
</div>
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="http://sphinx-doc.org/">Sphinx</a> 4.2.0.<br/>
</p>
</div>
</div>
</footer>
</body>
</html>