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
|
Contributing to Biopython
=========================
We welcome pull requests to fix bugs or add new features. Please read
http://biopython.org/wiki/Contributing for a general overview about
contributing - this file is primarily concerned with the practicalities.
Licensing
---------
Biopython is moving towards dual licensing the code. In your git commit and/or
pull request, please explicitly state that you agree to your contributions
being dual licensed under *both* our original "Biopython License Agreement"
and the more widely used "3-Clause BSD License" (see our LICENSE file for more
details).
Git Usage
---------
We have a git introduction online at http://biopython.org/wiki/GitUsage
If you are planning to make a pull request, start by creating a new branch
with a short but descriptive name (rather than using your master branch).
Coding Conventions
------------------
Biopython tries to follow the coding conventions laid out in PEP8 and PEP257,
with the notable exception of existing module names which are not lower case.
- http://www.python.org/dev/peps/pep-0008/
- http://www.python.org/dev/peps/pep-0257/
For docstrings (Python's in-code documentation) in addition to PEP257 we are
using reStructuredText (RST) markup language which allows basic formatting
like *italics* and **bold** once rendered into HTML webpages for our online
API documentation.
We use the continuous integration service TravisCI to enforce some of these
checks, so if you are making a contribution it is best to check this locally.
We use the tool ``flake8`` for code style checks, together with various
plugins which can be installed as follows::
$ pip install flake8 flake8-docstrings flake8-blind-except flake8-rst-docstrings
Unless you are using Python 2.7, please also install the bugbear plugin:
$ pip install flake8-bugbear
You can then run ``flake8`` directly as follows::
$ flake8 Bio/
$ flake8 BioSQL/
$ flake8 Tests/
$ flake8 Scripts/
$ flake8 Doc/examples/
Each of these folders has its own flake8 settings file, but in the long term
we would like all the code to follow the same strict settings.
You can run the reStructuredText checks with the ``restructuredtext-lint``
tool (also known as ``rst-lint``)::
$ pip install restructuredtext_lint
$ rst-lint --level warning *.rst
More simply, we currently suggest you install the git pre-commit hook described
here which will check our basic coding conventions as you work:
https://github.com/biopython/biopython/issues/493
Testing
-------
Any new feature or functionality will not be accepted without tests. Likewise
for any bug fix, we encourage including an additional test. See the testing
chapter in the Biopython Tutorial for more information on our test framework:
http://biopython.org/DIST/docs/tutorial/Tutorial.html
Local Testing
-------------
Please always run the style checks (see above) and the full test suite on
your local computer before submitting a pull request, e.g.::
$ git commit Bio/XXX.py Tests/test_XXX.py -m "Fixed bug 123"
$ python3.5 setup.py build
$ python3.5 setup.py test
If you have multiple versions of Python installed, ideally test them all
(the Python tool ``tox`` can be helpful here).
Continous Integration
---------------------
Once you submit your pull request on GitHub, several automated tests should
be run, and their results reported on the pull request.
We use TravisCI to run most of the Biopython tests (although currently only
under Linux, and not with all the optional dependencies included), plus also
check Python coding style using the ``flake8`` tool with the ``pydocstyle``
plugin (``flake8-docstrings``), and reStructuredText using ``rst-lint``.
https://travis-ci.org/biopython/biopython/branches
We use AppVeyor to run most of the tests under Windows (although currently
without any optional dependencies).
https://ci.appveyor.com/project/biopython/biopython/history
**The TravisCI and AppVeyor checks must pass before your pull request will
be merged.**
Some of the TravisCI and AppVeyor runs collect test coverage information via
CodeCov: https://codecov.io/github/biopython/biopython/
Ideally the CodeCov checks will also pass, but we currently do not insist
on this when reviewing pull requests.
|
