-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathcontribute.html
964 lines (755 loc) · 78.8 KB
/
contribute.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
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
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
<!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>Contribute to scikit-bio — scikit-bio</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=8878045cc6db502f8baf" rel="stylesheet" />
<link href="_static/styles/pydata-sphinx-theme.css?digest=8878045cc6db502f8baf" rel="stylesheet" />
<link rel="stylesheet" type="text/css" href="_static/pygments.css?v=8f2a1f02" />
<link rel="stylesheet" type="text/css" href="_static/copybutton.css?v=76b2166b" />
<link rel="stylesheet" type="text/css" href="_static/sphinx-design.min.css?v=95c83b7e" />
<link rel="stylesheet" type="text/css" href="_static/css/style.css?v=3e6c503c" />
<!-- So that users can add custom icons -->
<script src="_static/scripts/fontawesome.js?digest=8878045cc6db502f8baf"></script>
<!-- Pre-loaded scripts that we'll load fully later -->
<link rel="preload" as="script" href="_static/scripts/bootstrap.js?digest=8878045cc6db502f8baf" />
<link rel="preload" as="script" href="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf" />
<script src="_static/documentation_options.js?v=5929fcd5"></script>
<script src="_static/doctools.js?v=9bcbadda"></script>
<script src="_static/sphinx_highlight.js?v=dc90522c"></script>
<script src="_static/clipboard.min.js?v=a7894cd8"></script>
<script src="_static/copybutton.js?v=f281be69"></script>
<script src="_static/design-tabs.js?v=f930bc37"></script>
<script async="async" src="https://www.googletagmanager.com/gtag/js?id=UA-6636235-9"></script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){ dataLayer.push(arguments); }
gtag('js', new Date());
gtag('config', 'UA-6636235-9');
</script>
<script>
window.dataLayer = window.dataLayer || [];
function gtag(){ dataLayer.push(arguments); }
gtag('js', new Date());
gtag('config', 'UA-6636235-9');
</script>
<script>DOCUMENTATION_OPTIONS.pagename = 'contribute';</script>
<link rel="canonical" href="https://scikit.bio/contribute.html" />
<link rel="icon" href="_static/favicon.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="Coding guidelines" href="devdoc/code_guide.html" />
<link rel="prev" title="Learn scikit-bio" href="learn.html" />
<meta name="viewport" content="width=device-width, initial-scale=1"/>
<meta name="docsearch:language" content="en"/>
<meta name="docsearch:version" content="" />
</head>
<body data-bs-spy="scroll" data-bs-target=".bd-toc-nav" data-offset="180" data-bs-root-margin="0px 0px -60%" 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 class="bd-header navbar navbar-expand-lg bd-navbar d-print-none">
<div class="bd-header__inner bd-page-width">
<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/logo.svg" class="logo__image only-light" alt="scikit-bio"/>
<img src="_static/logo_inv.svg" class="logo__image only-dark pst-js-only" alt="scikit-bio"/>
</a></div>
</div>
<div class="col-lg-9 navbar-header-items">
<div class="me-auto navbar-header-items__center">
<div class="navbar-item">
<nav>
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item ">
<a class="nav-link nav-internal" href="install.html">
Install
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="learn.html">
Learn
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="docs/latest/index.html">
Documentation
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="#">
Contribute
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="https://github.com/scikit-bio/scikit-bio/discussions">
Community
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="https://github.com/scikit-bio/scikit-bio/blob/main/CHANGELOG.md">
Releases
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="about.html">
About
</a>
</li>
</ul>
</nav></div>
</div>
<div class="navbar-header-items__end">
<div class="navbar-item">
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i>
</button></div>
<div class="navbar-item"><ul class="navbar-icon-links"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/scikit-bio/scikit-bio" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/scikitbio" title="Twitter" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-twitter fa-lg" aria-hidden="true"></i>
<span class="sr-only">Twitter</span></a>
</li>
</ul></div>
</div>
</div>
<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 hide-on-wide">
<div class="sidebar-header-items sidebar-primary__section">
<div class="sidebar-header-items__center">
<div class="navbar-item">
<nav>
<ul class="bd-navbar-elements navbar-nav">
<li class="nav-item ">
<a class="nav-link nav-internal" href="install.html">
Install
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="learn.html">
Learn
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="docs/latest/index.html">
Documentation
</a>
</li>
<li class="nav-item current active">
<a class="nav-link nav-internal" href="#">
Contribute
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="https://github.com/scikit-bio/scikit-bio/discussions">
Community
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-external" href="https://github.com/scikit-bio/scikit-bio/blob/main/CHANGELOG.md">
Releases
</a>
</li>
<li class="nav-item ">
<a class="nav-link nav-internal" href="about.html">
About
</a>
</li>
</ul>
</nav></div>
</div>
<div class="sidebar-header-items__end">
<div class="navbar-item">
<button class="btn btn-sm nav-link pst-navbar-icon theme-switch-button pst-js-only" aria-label="Color mode" data-bs-title="Color mode" data-bs-placement="bottom" data-bs-toggle="tooltip">
<i class="theme-switch fa-solid fa-sun fa-lg" data-mode="light" title="Light"></i>
<i class="theme-switch fa-solid fa-moon fa-lg" data-mode="dark" title="Dark"></i>
<i class="theme-switch fa-solid fa-circle-half-stroke fa-lg" data-mode="auto" title="System Settings"></i>
</button></div>
<div class="navbar-item"><ul class="navbar-icon-links"
aria-label="Icon Links">
<li class="nav-item">
<a href="https://github.com/scikit-bio/scikit-bio" title="GitHub" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-github fa-lg" aria-hidden="true"></i>
<span class="sr-only">GitHub</span></a>
</li>
<li class="nav-item">
<a href="https://twitter.com/scikitbio" title="Twitter" class="nav-link pst-navbar-icon" rel="noopener" target="_blank" data-bs-toggle="tooltip" data-bs-placement="bottom"><i class="fa-brands fa-square-twitter fa-lg" aria-hidden="true"></i>
<span class="sr-only">Twitter</span></a>
</li>
</ul></div>
</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">Contribute to scikit-bio</span></li>
</ul>
</nav>
</div>
</div>
</div>
</div>
<div id="searchbox"></div>
<article class="bd-article">
<section id="contribute-to-scikit-bio">
<h1>Contribute to scikit-bio<a class="headerlink" href="#contribute-to-scikit-bio" title="Link to this heading">#</a></h1>
<p><strong>Scikit-bio</strong> is a community-driven open-source software project, and we warmly welcome your contributions!</p>
<p>We are interested in many types of contributions, including feature additions, bug fixes, continuous integration improvements, and documentation/website updates, additions, and fixes. Whether you are a researcher, educator, or developer; whether your interest lies in biology, mathematics, statistics, or computer science; your input is invaluable. You can help making scikit-bio a better software package for our entire community.</p>
<p>This document covers the information you may need to get started with contributing to scikit-bio. In addition, for a broader perspective, we recommend the inspiring guide: <a class="reference external" href="https://opensource.guide/how-to-contribute/">How to Contribute to Open Source</a>.</p>
<p>Visit our GitHub repository: <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/">scikit-bio/scikit-bio</a> for the source code of scikit-bio. You will need a GitHub account to interact with the scikit-bio codebase and community.</p>
<p>Valuable contributions can be made without or with minimum amount of coding. We detail various ways you can contribute below:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#ask-a-question">Ask a question</a> | <a class="reference internal" href="#report-an-error">Report an error</a> | <a class="reference internal" href="#suggest-a-new-feature">Suggest a new feature</a> | <a class="reference internal" href="#fix-a-typo">Fix a typo</a></p></li>
</ul>
<p>Contributing code to scikit-bio is a rigorous and rewarding process. We have prepared the following step-by-step guidelines:</p>
<ul class="simple">
<li><p><a class="reference internal" href="#before-coding">Before coding</a> | <a class="reference internal" href="#set-up-a-workspace">Set up a workspace</a> | <a class="reference internal" href="#write-code">Write code</a> | <a class="reference internal" href="#test-code">Test code</a> | <a class="reference internal" href="#document-code">Document code</a> | <a class="reference internal" href="#style-code">Style code</a> | <a class="reference internal" href="#submit-code">Submit code</a> | <a class="reference internal" href="#review-code">Review code</a></p></li>
</ul>
<p>In addition, there are separate documents covering advanced topics:</p>
<div class="toctree-wrapper compound">
<ul>
<li class="toctree-l1"><a class="reference internal" href="devdoc/code_guide.html">Coding guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="devdoc/doc_guide.html">Documentation guidelines</a></li>
<li class="toctree-l1"><a class="reference internal" href="devdoc/new_module.html">Adding a new module</a></li>
<li class="toctree-l1"><a class="reference internal" href="devdoc/review.html">Reviewing pull requests</a></li>
<li class="toctree-l1"><a class="reference internal" href="devdoc/release.html">Releasing a new version</a></li>
</ul>
</div>
<section id="ask-a-question">
<h2>Ask a question<a class="headerlink" href="#ask-a-question" title="Link to this heading">#</a></h2>
<p>Your inquiry matters! By asking questions in the scikit-bio <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/issues">issue tracker</a> or <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/discussions">discussion board</a>, you are not only giving us (and the community) the chance to help, but also let us assess the needs of users like you. Before asking a question, take a moment to search existing threads to see if there are any relevant ones. We also keep an eye on broader community forums such as Stack Overflow and BioStars for questions related to our scope.</p>
</section>
<section id="report-an-error">
<h2>Report an error<a class="headerlink" href="#report-an-error" title="Link to this heading">#</a></h2>
<p>The scikit-bio team is proud of our high-quality, well-tested codebase. That being said, no software is immune to errors, which may arise from bugs, overlooked edge cases, or confusions in documentation. In any situation, we would appreciate it if you can report the error you encountered to us.</p>
<p>You may <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/issues/new/choose">open an issue</a> to report the error. Please provide a detailed description of the error such that the developers can reproduce it. Specifically, you may include the following information in the report:</p>
<ol class="arabic simple">
<li><p>The exact <strong>command(s)</strong> necessary to reproduce the error.</p></li>
<li><p>The input <strong>file(s)</strong> necessary for reproducing the error. You may either attach the file in the issue (by dragging & dropping) if it is small, or provide a link to it otherwise. The file should only be as large as necessary to reproduce the error.</p></li>
</ol>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>For example, if you have a FASTA file with 10,000 sequences but the error only arises due to one of the sequences, create a new FASTA file with only that sequence, run the command that was giving you problems, and verify that you still get an error. Then post that command and link to the trimmed FASTA file.</p>
</div>
<p>This is <em>extremely</em> useful to the developers, and it is likely that if you don’t provide this information you’ll get a response asking for it. Often this process helps you to better understand the error as well.</p>
<p>We take error reports very seriously. Once confirmed that they should be fixed, we will update the code to fix them as soon as we can, and ship the update in the next scheduled release of scikit-bio. If the error could result in incorrect results or inability to access certain functionality, we may release a bug-fix version of scikit-bio ahead of the schedule.</p>
</section>
<section id="suggest-a-new-feature">
<h2>Suggest a new feature<a class="headerlink" href="#suggest-a-new-feature" title="Link to this heading">#</a></h2>
<p>We are always looking for new ideas to enhance scikit-bio’s capabilities, especially from users with unique research interests. If you believe there is an analysis or feature that could extend scikit-bio’s current offerings, we warmly invite you to share your suggestions with us.</p>
<p>Please describe why the functionality that you are suggesting is relevant. For it to be relevant, it should be demonstrably useful to scikit-bio users and it should also fit within the biology/bioinformatics domain. This typically means that a new analytic method is implemented (you should describe why it’s useful, ideally including a link to a paper that uses this method), or an existing method is enhanced (e.g., improved performance).</p>
<p>If the scope of the suggested method overlaps with any pre-existing methods in scikit-bio, we may request benchmark results comparing your method to the pre-existing ones (which would also be required for publication of your method) so pointing to a paper or other document containing benchmark results, or including benchmark results in your issue, will help.</p>
<p>Before suggesting a new feature, it is also a good idea to check whether the functionality exists in other Python packages, or if the feature would fit better in another Python package. For example, low-level statistical methods/tests may fit better in a project that is focused on statistics (e.g., <a class="reference external" href="https://scipy.org/">SciPy</a> or <a class="reference external" href="https://www.statsmodels.org/">statsmodels</a>).</p>
<p>If your proposal represents a significant research direction or requires a substantial suite of methods, we encourage you to consider establishing a formal academic or industrial collaboration with the scikit-bio team. For more details on this process, please refer to the <a class="reference internal" href="about.html#collaboration"><span class="std std-ref">Collaboration</span></a> section.</p>
</section>
<section id="fix-a-typo">
<h2>Fix a typo<a class="headerlink" href="#fix-a-typo" title="Link to this heading">#</a></h2>
<p>If you spot small errors such as typos, redundant spaces, broken links, missing citations etc. in the scikit-bio code or documentation, and want to give it a quick fix, you may follow the procedures detailed below. All procedures will take place in the web browser, and don’t involve creating anything in your local computer.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>This approach should not be applied to anything larger than small errors. For the latter, please read <a class="reference internal" href="#before-coding">Before coding</a>.</p>
</div>
<ol class="arabic simple">
<li><p>Locate the specific code file that needs to be fixed in the GitHub repository. If you are reading the documentation, you can click the <a class="reference external" href="about:blank">[source]</a> link next to the header to locate the corresponding code file.</p></li>
<li><p>In the top-right corner of the code viewer there is an Edit (<svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-pencil" viewBox="0 0 16 16" aria-hidden="true"><path d="M11.013 1.427a1.75 1.75 0 0 1 2.474 0l1.086 1.086a1.75 1.75 0 0 1 0 2.474l-8.61 8.61c-.21.21-.47.364-.756.445l-3.251.93a.75.75 0 0 1-.927-.928l.929-3.25c.081-.286.235-.547.445-.758l8.61-8.61Zm.176 4.823L9.75 4.81l-6.286 6.287a.253.253 0 0 0-.064.108l-.558 1.953 1.953-.558a.253.253 0 0 0 .108-.064Zm1.238-3.763a.25.25 0 0 0-.354 0L10.811 3.75l1.439 1.44 1.263-1.263a.25.25 0 0 0 0-.354Z"></path></svg>) button, with a prompt “Fork this repository and edit the file”. Click it. Then click the button <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">Fork this repository</span>. This will open GitHub’s <a class="reference external" href="https://docs.github.com/en/repositories/working-with-files/managing-files/editing-files">online file editor</a>.</p></li>
<li><p><strong>Edit the code</strong>.</p></li>
<li><p>When done, click <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">Commit changes…</span>. Then enter a commit message to describe what you did, like “Fixed a typo in the documentation of skbio.module.function”. Then click <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">Propose changes</span>.</p></li>
<li><p>You will be able to review the changes you made and compare with the original code <svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-git-compare" viewBox="0 0 16 16" aria-hidden="true"><path d="M9.573.677A.25.25 0 0 1 10 .854V2.5h1A2.5 2.5 0 0 1 13.5 5v5.628a2.251 2.251 0 1 1-1.5 0V5a1 1 0 0 0-1-1h-1v1.646a.25.25 0 0 1-.427.177L7.177 3.427a.25.25 0 0 1 0-.354ZM6 12v-1.646a.25.25 0 0 1 .427-.177l2.396 2.396a.25.25 0 0 1 0 .354l-2.396 2.396A.25.25 0 0 1 6 15.146V13.5H5A2.5 2.5 0 0 1 2.5 11V5.372a2.25 2.25 0 1 1 1.5 0V11a1 1 0 0 0 1 1ZM4 3.25a.75.75 0 1 0-1.5 0 .75.75 0 0 0 1.5 0ZM12.75 12a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Z"></path></svg>. If everything looks good to you, click <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">Create pull request</span>. Then enter a title and description that you think are informative to the scikit-bio maintainers. The <strong>title</strong> may or may not be the same as the commit message. In the <strong>description</strong>, you will need to answer a few questions by typing an <code class="docutils literal notranslate"><span class="pre">x</span></code> in the relevant checkboxes. You may also explain why the original code should be replaced by yours. Finally, click <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">Create pull request</span>.</p></li>
<li><p>This will create a <a class="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request">pull request</a> <svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-git-pull-request" viewBox="0 0 16 16" aria-hidden="true"><path d="M1.5 3.25a2.25 2.25 0 1 1 3 2.122v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.25 2.25 0 0 1 1.5 3.25Zm5.677-.177L9.573.677A.25.25 0 0 1 10 .854V2.5h1A2.5 2.5 0 0 1 13.5 5v5.628a2.251 2.251 0 1 1-1.5 0V5a1 1 0 0 0-1-1h-1v1.646a.25.25 0 0 1-.427.177L7.177 3.427a.25.25 0 0 1 0-.354ZM3.75 2.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm0 9.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm8.25.75a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Z"></path></svg>, i.e., the changes you made to the scikit-bio repository. A scikit-bio maintainer will review your pull request, and run necessary tests to make sure it is sound. You may be asked to clarify or to make modifications to your code. Please work with the maintainer by replying in the pull request.</p></li>
<li><p>If the maintainer believes that your code is good to go, they will <a class="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request">merge</a> it into the scikit-bio codebase. Once merged, the pull request webpage will have a purple notice <svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-git-merge" viewBox="0 0 16 16" aria-hidden="true"><path d="M5.45 5.154A4.25 4.25 0 0 0 9.25 7.5h1.378a2.251 2.251 0 1 1 0 1.5H9.25A5.734 5.734 0 0 1 5 7.123v3.505a2.25 2.25 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.95-.218ZM4.25 13.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm8.5-4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5ZM5 3.25a.75.75 0 1 0 0 .005V3.25Z"></path></svg>, saying: “Pull request successfully merged and closed”.</p></li>
<li><p>At this point, your contribution is completed 🎉. You may optionally click <span class="sd-sphinx-override sd-badge sd-bg-light sd-bg-text-light">Delete branch</span> to clean up your workspace. Then, you can move on, and enjoy the improved scikit-bio!</p></li>
</ol>
</section>
<section id="before-coding">
<h2>Before coding<a class="headerlink" href="#before-coding" title="Link to this heading">#</a></h2>
<p>We sincerely value your willingness to contribute code to scikit-bio (beyond reporting issues or correcting typos). This process can be intensive, particularly for those new to software engineering. The following sections detail the steps for contributing code to scikit-bio. Please review them carefully.</p>
<section id="discuss-your-plan">
<h3>Discuss your plan<a class="headerlink" href="#discuss-your-plan" title="Link to this heading">#</a></h3>
<p>When considering contributing code to scikit-bio, you should begin by posting an issue to the <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/issues">scikit-bio issue tracker</a>. The information that you include in that post will differ based on the type of contribution. The two types of issues discussed in <a class="reference internal" href="#report-an-error">Report an error</a> and <a class="reference internal" href="#suggest-a-new-feature">Suggest a new feature</a> can be a good start of the discussion.</p>
<p>The scikit-bio developers will respond to let you know if we agree with the addition or change. It’s very important that you go through this step to avoid spending time working on a feature that we are not interested in including in scikit-bio.</p>
</section>
<section id="take-existing-tasks">
<h3>Take existing tasks<a class="headerlink" href="#take-existing-tasks" title="Link to this heading">#</a></h3>
<p>Alternatively, if you’re looking to contribute where help is needed, you can explore the following types of issues:</p>
<ul class="simple">
<li><p><strong>Quick fix</strong>: Some of our issues are labeled as <code class="docutils literal notranslate"><span class="pre">quick</span> <span class="pre">fix</span></code>. Working on <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/issues?q=is%3Aopen+is%3Aissue+label%3A%22quick+fix%22">these issues</a> is a good way to get started with contributing to scikit-bio. These are usually small bugs or documentation errors that will only require one or a few lines of code to fix. Getting started by working on one of these issues will allow you to familiarize yourself with our development process before committing to a large amount of work (e.g., adding a new feature to scikit-bio). Please post a comment on the issue if you’re interested in working on one of these “quick fixes”.</p></li>
<li><p><strong>On deck</strong>: Once you are more comfortable with our development process, you can check out the <code class="docutils literal notranslate"><span class="pre">on</span> <span class="pre">deck</span></code> <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/labels/on%20deck">label</a> on our issue tracker. These issues represent what our current focus is in the project. As such, they are probably the best place to start if you are looking to join the conversation and contribute code.</p></li>
</ul>
</section>
</section>
<section id="set-up-a-workspace">
<h2>Set up a workspace<a class="headerlink" href="#set-up-a-workspace" title="Link to this heading">#</a></h2>
<p>To start contributing code to scikit-bio, you’ll need to prepare a local development environment. This section guides you through the process step-by-step.</p>
<ol class="arabic simple">
<li><p><a class="reference external" href="https://help.github.com/articles/fork-a-repo">Fork</a> the scikit-bio repository on the GitHub website. This will create a copy of the repository under your account, and you can access it using the URL: <code class="docutils literal notranslate"><span class="pre">https://github.com/urname/scikit-bio/</span></code> (<code class="docutils literal notranslate"><span class="pre">urname</span></code> is your GitHub account).</p></li>
<li><p><a class="reference external" href="https://docs.github.com/en/repositories/creating-and-managing-repositories/cloning-a-repository">Clone</a> the forked repository to your local computer. Specifically, in your forked repository, you may click the <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success"><> Code</span> button, make sure that you are under the “Local” - “SSH” tab, and copy the URL to the clipboard. It should typically be: <code class="docutils literal notranslate"><span class="pre">git@github.com:urname/scikit-bio.git</span></code>.</p></li>
</ol>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If the “SSH” tab is not available, it could mean that you have not set up an SSH key for your GitHub account. You may follow the instructions on <a class="reference external" href="https://docs.github.com/en/authentication/connecting-to-github-with-ssh">Connecting to GitHub with SSH</a> to set it up.</p>
</div>
<p>Then, open “Terminal” <svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-terminal" viewBox="0 0 16 16" aria-hidden="true"><path d="M0 2.75C0 1.784.784 1 1.75 1h12.5c.966 0 1.75.784 1.75 1.75v10.5A1.75 1.75 0 0 1 14.25 15H1.75A1.75 1.75 0 0 1 0 13.25Zm1.75-.25a.25.25 0 0 0-.25.25v10.5c0 .138.112.25.25.25h12.5a.25.25 0 0 0 .25-.25V2.75a.25.25 0 0 0-.25-.25ZM7.25 8a.749.749 0 0 1-.22.53l-2.25 2.25a.749.749 0 0 1-1.275-.326.749.749 0 0 1 .215-.734L5.44 8 3.72 6.28a.749.749 0 0 1 .326-1.275.749.749 0 0 1 .734.215l2.25 2.25c.141.14.22.331.22.53Zm1.5 1.5h3a.75.75 0 0 1 0 1.5h-3a.75.75 0 0 1 0-1.5Z"></path></svg> (or anything similar) in your local computer and navigate to a directory where you want to place the workspace, and execute:</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">urname</span><span class="o">/</span><span class="n">scikit</span><span class="o">-</span><span class="n">bio</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If this is the first time you use <code class="docutils literal notranslate"><span class="pre">git</span></code>, you may follow the <a class="reference external" href="https://docs.github.com/en/get-started/getting-started-with-git/set-up-git">Set up Git</a> guidelines to install Git and set your user name and email address.</p>
<p>This tutorial assumes that you will use the classical <code class="docutils literal notranslate"><span class="pre">git</span></code> to create a local development environment. If you prefer other methods such as <a class="reference external" href="https://cli.github.com/">GitHub CLI</a> or <a class="reference external" href="https://github.com/features/codespaces">Codespace</a>, please follow corresponding instructions.</p>
</div>
<p>This will create a directory <code class="docutils literal notranslate"><span class="pre">scikit-bio</span></code> containing all files in the repository. Enter the directory:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">cd</span> <span class="n">scikit</span><span class="o">-</span><span class="n">bio</span>
</pre></div>
</div>
<p>Add the official scikit-bio repo as the <strong>upstream</strong> of your fork:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">remote</span> <span class="n">add</span> <span class="n">upstream</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">scikit</span><span class="o">-</span><span class="n">bio</span><span class="o">/</span><span class="n">scikit</span><span class="o">-</span><span class="n">bio</span><span class="o">.</span><span class="n">git</span>
</pre></div>
</div>
<ol class="arabic simple" start="3">
<li><p>Create a development environment with necessary dependencies. This is typically done using <a class="reference external" href="https://conda.io/">Conda</a> (or <a class="reference external" href="https://mamba.readthedocs.io/en/latest/index.html">Mamba</a>, in which case the command <code class="docutils literal notranslate"><span class="pre">conda</span></code> in the following code should be replaced with <code class="docutils literal notranslate"><span class="pre">mamba</span></code>).</p></li>
</ol>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>If you do not have Conda (or Mamba) in your computer, you may install one of the distributions such as <a class="reference external" href="https://conda.io/miniconda.html">Miniconda</a>, <a class="reference external" href="https://github.com/conda-forge/miniforge">Miniforge</a> or <a class="reference external" href="https://www.anaconda.com/download/">Anaconda</a>.</p>
<p>We recommend Conda over other approaches such as <code class="docutils literal notranslate"><span class="pre">pip</span></code>, <code class="docutils literal notranslate"><span class="pre">pyenv</span></code>, and <code class="docutils literal notranslate"><span class="pre">virtualenv</span></code>. However, you are not blocked from using them in necessary situations.</p>
</div>
<p>Execute the following command (<code class="docutils literal notranslate"><span class="pre">skbio-dev</span></code> can be any name you like):</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">skbio</span><span class="o">-</span><span class="n">dev</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="o">--</span><span class="n">file</span> <span class="n">ci</span><span class="o">/</span><span class="n">conda_requirements</span><span class="o">.</span><span class="n">txt</span> <span class="o">--</span><span class="n">file</span> <span class="n">ci</span><span class="o">/</span><span class="n">requirements</span><span class="o">.</span><span class="n">test</span><span class="o">.</span><span class="n">txt</span> <span class="o">--</span><span class="n">file</span> <span class="n">ci</span><span class="o">/</span><span class="n">requirements</span><span class="o">.</span><span class="n">lint</span><span class="o">.</span><span class="n">txt</span> <span class="o">--</span><span class="n">file</span> <span class="n">ci</span><span class="o">/</span><span class="n">requirements</span><span class="o">.</span><span class="n">doc</span><span class="o">.</span><span class="n">txt</span>
</pre></div>
</div>
<p>When done, activate the environment:</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">skbio</span><span class="o">-</span><span class="n">dev</span>
</pre></div>
</div>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>This may be slightly different depending on the operating system. Refer to the <a class="reference external" href="https://docs.conda.io/">Conda documentation</a> to find instructions for your OS.</p>
</div>
<ol class="arabic" start="4">
<li><p>Install scikit-bio from source code:</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">deps</span> <span class="o">-</span><span class="n">e</span> <span class="o">.</span>
</pre></div>
</div>
</li>
</ol>
<p>This will install scikit-bio to the current conda environment. After this, you can use scikit-bio like a normal user (e.g., you can do <code class="docutils literal notranslate"><span class="pre">import</span> <span class="pre">skbio</span></code> in Python code). When you edit the code in the this directory, the changes will be immediately reflected as you use the software.</p>
<ol class="arabic" start="5">
<li><p>Test the installation:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">test</span>
</pre></div>
</div>
</li>
</ol>
<p>This will run all unit tests implemented in the scikit-bio codebase to check if the corresponding functionality works correctly. The output should only indicate passes and warnings, but no failures.</p>
<ol class="arabic" start="6">
<li><p>Activate pre-commit hooks:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">pre</span><span class="o">-</span><span class="n">commit</span> <span class="n">install</span>
</pre></div>
</div>
</li>
</ol>
<p>This will enable a set of tools that will automatically execute every time you commit changes to ensure code quality.</p>
</section>
<section id="write-code">
<h2>Write code<a class="headerlink" href="#write-code" title="Link to this heading">#</a></h2>
<p>Before you start writing code, you may discuss with the scikit-bio team to make sure that your intended contribution is relevant (see <a class="reference internal" href="#before-coding">Before coding</a> above). Next, you may work through the following steps to start coding.</p>
<ol class="arabic">
<li><p>Update your main branch such that it has the latest version of all files. This is especially important if you cloned a long time ago:</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">main</span>
<span class="n">git</span> <span class="n">pull</span> <span class="n">upstream</span> <span class="n">main</span>
</pre></div>
</div>
</li>
</ol>
<p>Optionally, you may do the following to keep your forked repository’s main branch up-to-date as well:</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">origin</span> <span class="n">main</span>
</pre></div>
</div>
<ol class="arabic" start="2">
<li><p>Create a new <a class="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/about-branches">branch</a> that you will make changes in:</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">mywork</span>
</pre></div>
</div>
</li>
</ol>
<p><code class="docutils literal notranslate"><span class="pre">mywork</span></code> is the name of the branch. What you name the branch is up to you, though we recommend including the issue number, if there is a relevant one (see above). For example, if you were addressing issue #42, you might name your branch <code class="docutils literal notranslate"><span class="pre">issue-42</span></code>.</p>
<div class="admonition warning">
<p class="admonition-title">Warning</p>
<p>It is not recommended that you directly code in your <code class="docutils literal notranslate"><span class="pre">main</span></code> branch.</p>
</div>
<ol class="arabic simple" start="3">
<li><p>Run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">test</span></code> to confirm that the tests pass before you make any changes.</p></li>
<li><p><strong>Edit the code</strong> using any code editor of your favor. Now it is the time to bring your creativity to scikit-bio!</p></li>
</ol>
<p>Scikit-bio’s <a class="reference internal" href="devdoc/code_guide.html"><span class="doc">coding guidelines</span></a> provide more details on how to write high-quality code. It is recommended that you read this document carefully and apply the guidelines in your code.</p>
</section>
<section id="test-code">
<h2>Test code<a class="headerlink" href="#test-code" title="Link to this heading">#</a></h2>
<p>Testing your code is an essential step to ensure its quality and functionality. For scikit-bio, we emphasize the importance of comprehensive testing to guarantee that your contribution works as expected. You might find testing tedious (it often costs more time than implementing the algorithm!), but it is a valuable step that will significantly enhance the robustness of your code, and will help fostering a culture of reliability and trust within our community. This section is to guide you through the testing process, providing you with the tools and knowledge to perform effective tests for scikit-bio.</p>
<section id="functional-test">
<h3>Functional test<a class="headerlink" href="#functional-test" title="Link to this heading">#</a></h3>
<p>You will want to test your code like a <em>user</em> would do: import the function, execute it on some input data, and examine whether the results are correct. You may install additional software such as <a class="reference external" href="https://jupyter.org/">Jupyter</a> in the same conda environment to make the testing process convenient and pleasant. There is no need to reinstall the modified scikit-bio package in a separate environment in order to test. As soon as you edit the code, the changes will immediately reflect when you use the code.</p>
<p>For example, you wrote a function <code class="docutils literal notranslate"><span class="pre">gc_content</span></code>, which calculates the fraction of <code class="docutils literal notranslate"><span class="pre">G</span></code> and <code class="docutils literal notranslate"><span class="pre">C</span></code> in a nucleotide sequence:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">gc_content</span><span class="p">(</span><span class="n">seq</span><span class="p">):</span>
<span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="mi">1</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">seq</span> <span class="k">if</span> <span class="n">x</span> <span class="ow">in</span> <span class="s2">"GC"</span><span class="p">)</span> <span class="o">/</span> <span class="nb">len</span><span class="p">(</span><span class="n">seq</span><span class="p">)</span>
</pre></div>
</div>
<p>You added this function to the code file <code class="docutils literal notranslate"><span class="pre">skbio/sequence/nucl.py</span></code>. It will be available for use in any Python code launched in the same conda environment:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">skbio.sequence.nucl</span><span class="w"> </span><span class="kn">import</span> <span class="n">gc_content</span>
</pre></div>
</div>
<p>Now test the function on some data. For example, you would expect that <code class="docutils literal notranslate"><span class="pre">gc_content("ACGT")</span></code> and <code class="docutils literal notranslate"><span class="pre">gc_content("GGATCCGC")</span></code> return 0.5 and 0.75, respectively. Is that the case?</p>
<p>We highly recommend that you use real-world biological data in addition to small, dummy data for testing. This will let you evaluate the robustness and scalability of your code in real-world applications. For example, DNA sequences retrieved from public databases may contain lowercase letters, and you will find that the <code class="docutils literal notranslate"><span class="pre">gc_content</span></code> function cannot handle them properly. For another instance, a FASTQ file with ten million sequences (which is common) may cost a function forever to process, in which case you should consider optimization.</p>
</section>
<section id="unit-test">
<h3>Unit test<a class="headerlink" href="#unit-test" title="Link to this heading">#</a></h3>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Unit_testing">Unit testing</a> involves testing the smallest units of your code, such as classes, functions, and methods, to ensure they function correctly in isolation. It is a fundamental best practice in software engineering, but is often overlooked by beginners. Unit testing is made easier by writing test code alongside the algorithm code. Both types of code are integrated into the scikit-bio codebase. This test code is then regularly executed whenever changes are made to ensure that the intended behavior remains consistent over time.</p>
<p>For example, the test code for the <code class="docutils literal notranslate"><span class="pre">gc_content</span></code> may live in <code class="docutils literal notranslate"><span class="pre">skbio/sequence/tests/test_nucl.py</span></code>, under class <code class="docutils literal notranslate"><span class="pre">TestNucl</span></code>, as a method <code class="docutils literal notranslate"><span class="pre">test_gc_content</span></code>. It may read like:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">test_gc_content</span><span class="p">(</span><span class="bp">self</span><span class="p">):</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">gc_content</span><span class="p">(</span><span class="s2">"ACGT"</span><span class="p">),</span> <span class="mf">0.5</span><span class="p">)</span>
<span class="bp">self</span><span class="o">.</span><span class="n">assertEqual</span><span class="p">(</span><span class="n">gc_content</span><span class="p">(</span><span class="s2">"GGATCCGC"</span><span class="p">),</span> <span class="mf">0.75</span><span class="p">)</span>
<span class="o">...</span>
</pre></div>
</div>
<p>You can run this test with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">python</span> <span class="n">skbio</span><span class="o">/</span><span class="n">sequence</span><span class="o">/</span><span class="n">tests</span><span class="o">/</span><span class="n">test_nucl</span><span class="o">.</span><span class="n">py</span> <span class="n">TestNucl</span><span class="o">.</span><span class="n">test_gc_content</span>
</pre></div>
</div>
<p>The screen output will tell you whether the test passed, and if not, what went wrong. This information will help you debug your code.</p>
<p>Ideally, every line of the code should be covered by unit test(s). For example, if your function has an <code class="docutils literal notranslate"><span class="pre">if</span></code> statement, both <code class="docutils literal notranslate"><span class="pre">True</span></code> and <code class="docutils literal notranslate"><span class="pre">False</span></code> situations should be tested.</p>
<p>It is a good practice to test all types of cases you can think of, including normal cases and <a class="reference external" href="https://en.wikipedia.org/wiki/Edge_case">edge cases</a>. For example, an empty sequence (<code class="docutils literal notranslate"><span class="pre">""</span></code>) will cause the <code class="docutils literal notranslate"><span class="pre">gc_content</span></code> function to crash, because zero cannot serve as a denominator in an equation. Having edge cases like this will help you to identify limitations of your code and think whether you should implement special handling to avoid problems.</p>
<p>You should also test whether the changed code fits into scikit-bio without causing problems in the other parts of the codebase. There is a convenient command to run all unit tests implemented in scikit-bio:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">test</span>
</pre></div>
</div>
<p>Alternatively, you may run all unit tests in a Python session (including Jupyter):</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="gp">>>> </span><span class="kn">from</span><span class="w"> </span><span class="nn">skbio.test</span><span class="w"> </span><span class="kn">import</span> <span class="n">pytestrunner</span>
<span class="gp">>>> </span><span class="n">pytestrunner</span><span class="p">()</span>
</pre></div>
</div>
</section>
<section id="code-coverage">
<h3>Code coverage<a class="headerlink" href="#code-coverage" title="Link to this heading">#</a></h3>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Code_coverage">Code coverage</a> refers to the percentage of source code lines covered by unit tests. It is an assessment of the quality of a software project. In scikit-bio, code coverage can be calculated using the following command:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">coverage</span> <span class="n">run</span> <span class="o">-</span><span class="n">m</span> <span class="n">skbio</span><span class="o">.</span><span class="n">test</span> <span class="o">&&</span> <span class="n">coverage</span> <span class="n">report</span>
</pre></div>
</div>
<p>This will report the coverage of each code file and the entire codebase. If the coverage decreased for the file you edited, you may have missed some anticipated unit tests. You can create a detailed HTML report with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">coverage</span> <span class="n">html</span>
</pre></div>
</div>
<p>Then open <code class="docutils literal notranslate"><span class="pre">htmlcov/index.html</span></code> in a web browser, navigate to the page for the relevant code file, and check which lines of your code are not covered by unit tests. Work on them to bring back coverage.</p>
<p>Please read the <a class="reference internal" href="devdoc/code_guide.html#how-should-i-test-my-code"><span class="std std-ref">How should I test my code?</span></a> section of the coding guidelines to learn more about unit testing.</p>
</section>
</section>
<section id="document-code">
<h2>Document code<a class="headerlink" href="#document-code" title="Link to this heading">#</a></h2>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Software_documentation">Documentation</a> is a vital part of software engineering, especially for projects like scikit-bio, which involve many contributors and are designed to endure over time. Documentation helps everyone – users and developers – get on the same page. It also helps you, as even seasoned developers can lose track of their own coding logic over time. Also remember that scikit-bio brings together people from various fields, and nobody is expected to have the same level of understanding across all disciplines. Therefore, documenting your code with the broader audience in mind is important. This section will cover the basics of documenting your code in a manner that benefits the scikit-bio community at large.</p>
<p>Scikit-bio’s <a class="reference internal" href="devdoc/doc_guide.html"><span class="doc">documentation guidelines</span></a> provide more details on how to write effective documentation.</p>
<section id="comments">
<h3>Comments<a class="headerlink" href="#comments" title="Link to this heading">#</a></h3>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Comment_(computer_programming)">Comments</a> in the source code explain the rationale to fellow developers. Please make comments frequently in your code, especially where the code itself is not that intuitive. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="c1"># Perform eigendecomposition on the covariance matrix of data.</span>
<span class="c1"># w and v are eigenvalues and eigenvectors, respectively.</span>
<span class="c1"># eigh is used in favor of eig to avoid returning complex numbers due to</span>
<span class="c1"># matrix asymmetry caused by floating point errors.</span>
<span class="c1"># Discussed in: https://stackoverflow.com/questions/12345678/</span>
<span class="n">w</span><span class="p">,</span> <span class="n">v</span> <span class="o">=</span> <span class="n">np</span><span class="o">.</span><span class="n">linalg</span><span class="o">.</span><span class="n">eig</span><span class="p">(</span><span class="n">np</span><span class="o">.</span><span class="n">cov</span><span class="p">(</span><span class="n">X</span><span class="p">))</span>
</pre></div>
</div>
<p>Please read the <a class="reference internal" href="devdoc/code_guide.html#how-should-i-write-comments"><span class="std std-ref">How should I write comments?</span></a> section of the coding guidelines to learn more about writing comments.</p>
</section>
<section id="docstrings">
<h3>Docstrings<a class="headerlink" href="#docstrings" title="Link to this heading">#</a></h3>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Docstring">Docstrings</a> are structured text blocks associated with each unit of the code that detail the usage of the code. Docstrings will be rendered to the software documentation. That is, <em>users</em> (not just developers) will read them. Therefore, docstrings are critical if you want your code to be used, and in the correct way.</p>
<p>Below is a very simple example for the <code class="docutils literal notranslate"><span class="pre">gc_content</span></code>. The lines between the triple double quotes (<code class="docutils literal notranslate"><span class="pre">"""</span></code>) are the docstring:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">gc_content</span><span class="p">(</span><span class="n">seq</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Calculate the GC content of a nucleotide sequence.</span>
<span class="sd"> Parameters</span>
<span class="sd"> ----------</span>
<span class="sd"> seq : str</span>
<span class="sd"> Input sequence.</span>
<span class="sd"> Returns</span>
<span class="sd"> -------</span>
<span class="sd"> float</span>
<span class="sd"> Fraction of G and C.</span>
<span class="sd"> """</span>
<span class="k">return</span> <span class="nb">sum</span><span class="p">(</span><span class="mi">1</span> <span class="k">for</span> <span class="n">x</span> <span class="ow">in</span> <span class="n">seq</span> <span class="k">if</span> <span class="n">x</span> <span class="ow">in</span> <span class="s2">"GC"</span><span class="p">)</span> <span class="o">/</span> <span class="nb">len</span><span class="p">(</span><span class="n">seq</span><span class="p">)</span>
</pre></div>
</div>
<p>As shown, the docstring explains the purpose, the parameter(s), and the return value(s) of the function. In more complicated cases, the docstring should also include example usage, potential errors, related functions, mathematics behind the algorithm, references to webpages or literature, etc. Every public-facing component should have a docstring.</p>
<p>Please read the <a class="reference internal" href="devdoc/doc_guide.html#docstring-style"><span class="std std-ref">Docstring style</span></a> section of the documentation guidelines to learn more about writing docstrings.</p>
</section>
<section id="doctests">
<h3>Doctests<a class="headerlink" href="#doctests" title="Link to this heading">#</a></h3>
<p>You may consider adding <strong>example usages</strong> of your code to its docstring. For example:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="k">def</span><span class="w"> </span><span class="nf">gc_content</span><span class="p">(</span><span class="n">seq</span><span class="p">):</span>
<span class="w"> </span><span class="sd">"""Calculate the GC content of a nucleotide sequence.</span>
<span class="sd"> ...</span>
<span class="sd"> Examples</span>
<span class="sd"> --------</span>
<span class="sd"> >>> from skbio.sequence.nucl import gc_content</span>
<span class="sd"> >>> gc_content("ACGT")</span>
<span class="sd"> 0.5</span>
<span class="sd"> """</span>
<span class="o">...</span>
</pre></div>
</div>
<p>The example code and its output must match. This is ensured by <a class="reference external" href="https://docs.python.org/3/library/doctest.html">doctest</a>. When you run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">test</span></code> (see above), doctests are automatically executed as part of the test suite. You may fix any issues according to the screen output.</p>
</section>
<section id="html-rendering">
<h3>HTML rendering<a class="headerlink" href="#html-rendering" title="Link to this heading">#</a></h3>
<p>After completing docstrings, you will want to check how they look like when rendered to the documentation webpages. You may build the entire HTML documentation package locally with:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">make</span> <span class="n">doc</span>
</pre></div>
</div>
<p>The built documentation will be at <code class="docutils literal notranslate"><span class="pre">doc/build/html/index.html</span></code>, and can be examined using your web browser. If errors arise during the building process, or the rendered webpages don’t look as anticipated, you should address the issues accordingly.</p>
</section>
<section id="changelog">
<h3>Changelog<a class="headerlink" href="#changelog" title="Link to this heading">#</a></h3>
<p>Please mention your changes in <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/blob/main/CHANGELOG.md">CHANGELOG.md</a>. This file informs scikit-bio <em>users</em> of changes made in each release, so be sure to describe your changes with this audience in mind. It is especially important to note API additions and changes, particularly if they are backward-incompatible, as well as bug fixes. Be sure to make your updates under the section designated for the latest development version of scikit-bio (this will be at the top of the file). Describe your changes in detail under the most appropriate section heading(s). For example, if your pull request fixes a bug, describe the bug fix under the “Bug fixes” section of the changelog. Please also include a link to the issue(s) addressed by your changes.</p>
</section>
</section>
<section id="style-code">
<h2>Style code<a class="headerlink" href="#style-code" title="Link to this heading">#</a></h2>
<p><a class="reference external" href="https://en.wikipedia.org/wiki/Programming_style">Code style</a> is a set of rules for formatting and structuring code in a particular software project. Although violating these rules won’t cause errors in executing the code, adhering to them ensures that the codebase remains uniform and professional, and facilitates team collaboration.</p>
<p>Scikit-bio utilizes the <a class="reference external" href="https://docs.astral.sh/ruff/">Ruff</a> program for autoformatting and linting to ensure code consistency and quality. The rules are specified in <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/blob/main/pyproject.toml">pyproject.toml</a>. Basically, we largely adopted the <a class="reference external" href="https://black.readthedocs.io/">Black</a> code style.</p>
<p>When you <a class="reference external" href="#set-up-a-workspace">set up the development environment</a>, Ruff was already installed and integrated into a <a class="reference external" href="https://github.com/astral-sh/ruff-pre-commit">pre-commit hook</a>. This means that Ruff will automatically format and lint your code every time you commit changes (see <a class="reference internal" href="#submit-code">Submit code</a> below). Therefore <em>you are not required to take any explicit action</em>. However, you can still manually run Ruff to check and fix issues in specific code files you have worked on:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ruff</span> <span class="n">check</span> <span class="o">--</span><span class="n">fix</span> <span class="n">mycode</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>If Ruff identifies any errors that cannot be automatically fixed, you will need to manually fix them based on Ruff’s feedback. When done, let Ruff reformat your code:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">ruff</span> <span class="nb">format</span> <span class="n">mycode</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
<p>You will notice the improvement in your code’s appearance before and after using Ruff. While it is always beneficial to strive for professional-looking code from the start, the necessity for perfection has lessened with the advent of tools like Ruff.</p>
</section>
<section id="submit-code">
<h2>Submit code<a class="headerlink" href="#submit-code" title="Link to this heading">#</a></h2>
<p>Having completed, tested, and documented your code, you may now believe it deserves a place in scikit-bio to benefit the community. This section outlines the steps to submit your code to the official scikit-bio repository.</p>
<ol class="arabic">
<li><p>Add any new code file(s) you created to the git repository:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">add</span> <span class="n">path</span><span class="o">/</span><span class="n">to</span><span class="o">/</span><span class="n">mycode</span><span class="o">.</span><span class="n">py</span>
</pre></div>
</div>
</li>
</ol>
<p>Alternatively, if you have multiple new files, you can add them all at once:</p>
<div class="highlight-default notranslate"><div class="highlight"><pre><span></span><span class="n">git</span> <span class="n">add</span> <span class="o">.</span>
</pre></div>
</div>
<ol class="arabic" start="2">
<li><p><a class="reference external" href="https://github.com/git-guides/git-commit">Commit</a> the changes (this is like “saving” your code in the current branch):</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">am</span> <span class="s2">"describe what I did"</span>
</pre></div>
</div>
</li>
</ol>
<p>Here, “describe what I did” is the placeholder of a <em>commit message</em>. You should write a meaningful commit message to describe what you did. We recommend following <a class="reference external" href="https://numpy.org/doc/stable/dev/development_workflow.html#writing-the-commit-message">NumPy’s commit message guidelines</a>, including the usage of commit tags (i.e., starting commit messages with acronyms such <code class="docutils literal notranslate"><span class="pre">ENH</span></code>, <code class="docutils literal notranslate"><span class="pre">BUG</span></code>, etc.).</p>
<p>The <cite>commit</cite> command will trigger the <a class="reference external" href="https://pre-commit.com/">pre-commit hook</a>, which automatically runs Ruff to check and fix any code style problems (see <a class="reference internal" href="#style-code">Style code</a> above). If there are any errors flagged by Ruff, you will need to resolve them and commit again.</p>
<ol class="arabic" start="3">
<li><p>Merge the latest code from the official scikit-bio repository to your local 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">merge</span> <span class="n">upstream</span><span class="o">/</span><span class="n">main</span>
</pre></div>
</div>
</li>
</ol>
<p>This step is important as it ensures that your code doesn’t conflict with any recent updates in the official repository. This could happen as there are other developers simultaneously working on the project.</p>
<p>If there are conflicts, you will need to <a class="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github">resolve the conflicts</a> by editing the affected files. When done, run <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">add</span></code> on those files, then run <code class="docutils literal notranslate"><span class="pre">git</span> <span class="pre">commit</span></code> with a relevant commit message (such as “resolved merge conflicts”).</p>
<ol class="arabic" start="4">
<li><p>Run <code class="docutils literal notranslate"><span class="pre">make</span> <span class="pre">test</span></code> for the last time to ensure that your changes don’t cause anything to break.</p></li>
<li><p>Once the tests pass, you should push your changes to your forked repository on GitHub using:</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">origin</span> <span class="n">mywork</span>
</pre></div>
</div>
</li>
<li><p>Navigate to the GitHub website, and create a <a class="reference external" href="https://help.github.com/articles/using-pull-requests">pull request</a> from your <code class="docutils literal notranslate"><span class="pre">mywork</span></code> branch to the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch of the official scikit-bio repository. Usually, GitHub will prompt you to do so, and you may click the <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">Compare & pull request</span> button to initiate this process. If not, you can invoke a <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">New pull request</span> under the “<svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-git-pull-request" viewBox="0 0 16 16" aria-hidden="true"><path d="M1.5 3.25a2.25 2.25 0 1 1 3 2.122v5.256a2.251 2.251 0 1 1-1.5 0V5.372A2.25 2.25 0 0 1 1.5 3.25Zm5.677-.177L9.573.677A.25.25 0 0 1 10 .854V2.5h1A2.5 2.5 0 0 1 13.5 5v5.628a2.251 2.251 0 1 1-1.5 0V5a1 1 0 0 0-1-1h-1v1.646a.25.25 0 0 1-.427.177L7.177 3.427a.25.25 0 0 1 0-.354ZM3.75 2.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm0 9.5a.75.75 0 1 0 0 1.5.75.75 0 0 0 0-1.5Zm8.25.75a.75.75 0 1 0 1.5 0 .75.75 0 0 0-1.5 0Z"></path></svg> pull request” tab.</p></li>
<li><p>Enter a meaningful title and a description of your code in the pull request. You may mention the issue you attempt to address in the description, such as “Resolves #42”. This will <a class="reference external" href="https://docs.github.com/en/issues/tracking-your-work-with-issues/linking-a-pull-request-to-an-issue">link your pull request to the issue</a>. You will also need to answer a few questions by either typing an <code class="docutils literal notranslate"><span class="pre">x</span></code> in the checkboxes that apply to your code or leaving them empty otherwise. These questions can be found in <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/blob/main/.github/PULL_REQUEST_TEMPLATE.md">PULL_REQUEST_TEMPLATE.md</a>. When done, click <span class="sd-sphinx-override sd-badge sd-bg-success sd-bg-text-success">Create pull request</span>.</p></li>
</ol>
</section>
<section id="review-code">
<h2>Review code<a class="headerlink" href="#review-code" title="Link to this heading">#</a></h2>
<p>Your <a class="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/about-pull-request-reviews">pull request will be reviewed</a> by one or more maintainers of scikit-bio. These reviews are intended to confirm a few points:</p>
<ul class="simple">
<li><p>Your code provides relevant changes or additions to scikit-bio.</p></li>
<li><p>Your code adheres to our coding guidelines.</p></li>
<li><p>Your code is sufficiently well-tested.</p></li>
<li><p>Your code is sufficiently well-documented.</p></li>
</ul>
<p>This process is designed to ensure the quality of scikit-bio and can be a very useful experience for new developers.</p>
<p>Typically, the reviewer will launch some automatic checks on your code. These checks are defined in <a class="extlink-repo reference external" href="https://github.com/scikit-bio/scikit-bio/blob/main/.github/workflows/ci.yml">ci.yml</a>. They involve:</p>
<ul class="simple">
<li><p>Full unit test suite and doctests execute without errors in all supported software and hardware environments.</p></li>
<li><p>C code can be correctly compiled.</p></li>
<li><p>Cython code is correctly generated.</p></li>
<li><p>Documentation can be built.</p></li>
<li><p>Code coverage is maintained or improved.</p></li>
<li><p>Code passes linting.</p></li>
</ul>
<p>The checks may take several to a few dozen minutes. If some check(s) fail, you may click “Details” in these checks to view the error messages, and fix the issues accordingly.</p>
<p>Meanwhile, the reviewer will comment on your code inline and/or below. They may request changes (which is very common). Please work with the reviewer to improve your code.</p>
<p>You should revise your code in your local branch. When completed, commit and push your code again (steps 1-5 of <a class="reference internal" href="#submit-code">Submit code</a>). This will automatically update your pull request and restart the checks. <em>Don’t issue a new pull request</em>.</p>
<div class="admonition note">
<p class="admonition-title">Note</p>
<p>Particularly for big changes, if you’d like feedback on your code in the form of a code review as you work, you should request help in the issue that you created and one of the scikit-bio maintainers will work with you to perform regular code reviews. This can greatly reduce development time. We highly recommend that new developers take advantage of this rather than submitting a pull request with a massive amount of code. That can lead to frustration when the developer thinks they are done but the reviewer requests large amounts of changes, and it also makes it harder to review.</p>
</div>
<p>Please read <a class="reference internal" href="devdoc/review.html"><span class="doc">Reviewing pull requests</span></a> for more details on how pull requests should be reviewed in the scikit-bio project.</p>
<p>After your code has been improved and the reviewer has approved it, they will <a class="reference external" href="https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/incorporating-changes-from-a-pull-request/merging-a-pull-request">merge your pull request</a> into the <code class="docutils literal notranslate"><span class="pre">main</span></code> branch of the official scikit-bio repository. This will be indicated by a note: <svg version="1.1" width="1.0em" height="1.0em" class="sd-octicon sd-octicon-git-merge" viewBox="0 0 16 16" aria-hidden="true"><path d="M5.45 5.154A4.25 4.25 0 0 0 9.25 7.5h1.378a2.251 2.251 0 1 1 0 1.5H9.25A5.734 5.734 0 0 1 5 7.123v3.505a2.25 2.25 0 1 1-1.5 0V5.372a2.25 2.25 0 1 1 1.95-.218ZM4.25 13.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5Zm8.5-4.5a.75.75 0 1 0 0-1.5.75.75 0 0 0 0 1.5ZM5 3.25a.75.75 0 1 0 0 .005V3.25Z"></path></svg> “Pull request successfully merged and closed”.</p>
<p>Congratulations! Your code is now an integral part of scikit-bio, and will benefit the broader community. You have successfully completed your contribution, and we extend our appreciation to you! 🎉🎉🎉”</p>
</section>
</section>
</article>
</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 class="bd-toc-nav page-toc" aria-labelledby="pst-page-navigation-heading-2">
<ul class="visible nav section-nav flex-column">
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#ask-a-question">Ask a question</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#report-an-error">Report an error</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#suggest-a-new-feature">Suggest a new feature</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#fix-a-typo">Fix a typo</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#before-coding">Before coding</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#discuss-your-plan">Discuss your plan</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#take-existing-tasks">Take existing tasks</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#set-up-a-workspace">Set up a workspace</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#write-code">Write code</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#test-code">Test code</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#functional-test">Functional test</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#unit-test">Unit test</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#code-coverage">Code coverage</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#document-code">Document code</a><ul class="nav section-nav flex-column">
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#comments">Comments</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#docstrings">Docstrings</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#doctests">Doctests</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#html-rendering">HTML rendering</a></li>
<li class="toc-h3 nav-item toc-entry"><a class="reference internal nav-link" href="#changelog">Changelog</a></li>
</ul>
</li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#style-code">Style code</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#submit-code">Submit code</a></li>
<li class="toc-h2 nav-item toc-entry"><a class="reference internal nav-link" href="#review-code">Review code</a></li>
</ul>
</nav></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=8878045cc6db502f8baf"></script>
<script defer src="_static/scripts/pydata-sphinx-theme.js?digest=8878045cc6db502f8baf"></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 2014-2025, scikit-bio development team.
<br/>
</p>
</div>
</div>
<div class="footer-items__center">
<div class="footer-item">
<p class="sphinx-version">
Created using <a href="https://www.sphinx-doc.org/">Sphinx</a> 8.1.3.
<br/>
</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.16.1.
</p></div>
</div>
</div>
</footer>
</body>
</html>