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
|
Contributing to DueCredit
=========================
[gh-duecredit]: https://github.com/duecredit/duecredit
Files organization
------------------
- `duecredit/` is the main Python module where major development is happening,
with major submodules being:
- `cmdline/` contains commands for the command line interface. See any of
the `cmd_*.py` files here for an example
- `tests/` all unit- and regression- tests
- `utils.py` provides convenience helpers used by unit-tests such as
`@with_tree`, `@serve_path_via_http` and other decorators
- `tools/` might contain helper utilities used during development, testing, and
benchmarking of DueCredit. Implemented in any most appropriate language
(Python, bash, etc.)
How to contribute
-----------------
The preferred way to contribute to the DueCredit code base is
to fork the [main repository][gh-duecredit] on GitHub. Here
we outline the workflow used by the developers:
0. Have a clone of our main [project repository][gh-duecredit] as `origin`
remote in your git:
git clone git://github.com/duecredit/duecredit
1. Fork the [project repository][gh-duecredit]: click on the 'Fork'
button near the top of the page. This creates a copy of the code
base under your account on the GitHub server.
2. Add your forked clone as a remote to the local clone you already have on your
local disk:
git remote add gh-YourLogin git@github.com:YourLogin/duecredit.git
git fetch gh-YourLogin
To ease addition of other github repositories as remotes, here is
a little bash function/script to add to your `~/.bashrc`:
ghremote () {
url="$1"
proj=${url##*/}
url_=${url%/*}
login=${url_##*/}
git remote add gh-$login $url
git fetch gh-$login
}
thus you could simply run:
ghremote git@github.com:YourLogin/duecredit.git
to add the above `gh-YourLogin` remote.
3. Create a branch (generally off the `origin/master`) to hold your changes:
git checkout -b nf-my-feature
and start making changes. Ideally, use a prefix signaling the purpose of the
branch
- `nf-` for new features
- `bf-` for bug fixes
- `rf-` for refactoring
- `doc-` for documentation contributions (including in the code docstrings).
We recommend to not work in the ``master`` branch!
4. Work on this copy on your computer using Git to do the version control. When
you're done editing, do:
git add modified_files
git commit
to record your changes in Git. Ideally, prefix your commit messages with the
`NF`, `BF`, `RF`, `DOC` similar to the branch name prefixes, but you could
also use `TST` for commits concerned solely with tests, and `BK` to signal
that the commit causes a breakage (e.g. of tests) at that point. Multiple
entries could be listed joined with a `+` (e.g. `rf+doc-`). See `git log` for
examples. If a commit closes an existing DueCredit issue, then add to the end
of the message `(Closes #ISSUE_NUMER)`
5. Push to GitHub with:
git push -u gh-YourLogin nf-my-feature
Finally, go to the web page of your fork of the DueCredit repo, and click
'Pull request' (PR) to send your changes to the maintainers for review. This
will send an email to the committers. You can commit new changes to this branch
and keep pushing to your remote -- github automagically adds them to your
previously opened PR.
(If any of the above seems like magic to you, then look up the
[Git documentation](http://git-scm.com/documentation) on the web.)
Quality Assurance
-----------------
It is recommended to check that your contribution complies with the following
rules before submitting a pull request:
- All public methods should have informative docstrings with sample usage
presented as doctests when appropriate.
- All other tests pass when everything is rebuilt from scratch.
- New code should be accompanied by tests.
### Tests
All tests are available under `duecredit/tests`. To execute tests, the codebase
needs to be "installed" in order to generate scripts for the entry points. For
that, the recommended course of action is to use `virtualenv`, e.g.
```sh
virtualenv --system-site-packages venv-tests
source venv-tests/bin/activate
pip install -e '.[tests]'
```
On Debian-based systems you might need to install some C-libraries to guarantee
installation (building) of some Python modules we use. So for `lxml` please first
```sh
sudo apt-get install libxml2-dev libxslt1-dev
```
On Mac OS X Yosemite additional steps are required to make `lxml` work properly
(see [this stackoverflow
answer](https://stackoverflow.com/questions/19548011/cannot-install-lxml-on-mac-os-x-10-9/26544099#26544099?newreg=d3394d8210cc4779accfac05fe5c9b21)).
We recommend using homebrew to install the same dependencies
(see the [Homebrew website](http://brew.sh/) to install it), then run
```sh
brew install libxml2 libxslt
brew link libxml2 --force
brew link libxslt --force
```
note that this will override the default libraries installed with Mac
OS X.
Then use that virtual environment to run the tests, via
```sh
python -m py.test -s -v duecredit
```
or similarly,
```sh
py.test -s -v duecredit
```
then to later deactivate the virtualenv just simply enter
```sh
deactivate
```
### Coverage
You can also check for common programming errors with the following tools:
- Code with good unittest coverage (at least 80%), check with:
pip install pytest coverage
coverage run --source duecredit -m py.test
coverage report
### Linting
We are not (yet) fully PEP8 compliant, so please use these tools as
guidelines for your contributions, but not to PEP8 entire code
base.
[beyond-pep8]: https://www.youtube.com/watch?v=wf-BqAjZb8M
*Sidenote*: watch [Raymond Hettinger - Beyond PEP 8][beyond-pep8]
- No pyflakes warnings, check with:
pip install pyflakes
pyflakes path/to/module.py
- No PEP8 warnings, check with:
pip install pep8
pep8 path/to/module.py
- AutoPEP8 can help you fix some of the easy redundant errors:
pip install autopep8
autopep8 path/to/pep8.py
Also, some team developers use
[PyCharm community edition](https://www.jetbrains.com/pycharm) which
provides built-in PEP8 checker and handy tools such as smart
splits/joins making it easier to maintain code following the PEP8
recommendations. NeuroDebian provides `pycharm-community-sloppy`
package to ease pycharm installation even further.
Easy Issues
-----------
A great way to start contributing to DueCredit is to pick an item from the list of
[Easy issues](https://github.com/duecredit/duecredit/labels/easy) in the issue
tracker. Resolving these issues allows you to start contributing to the project
without much prior knowledge. Your assistance in this area will be greatly
appreciated by the more experienced developers as it helps free up their time to
concentrate on other issues.
|
