-
Notifications
You must be signed in to change notification settings - Fork 10
/
how_to_contribute.md
145 lines (111 loc) · 5.47 KB
/
how_to_contribute.md
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
Getting Started!
================
First of all: thank you!
Contributions can be made in different ways, not only code! As we follow
the
[all-contributors](https://github.com/all-contributors/all-contributors)
specification, any contribution will be recognised accordingly.
Follow these steps to get started:
1. Have a look at the [contributor guide](contributor_guide.md) page as
well as the [code of conduct](code_of_conduct.md).
2. Make sure that you have a GitHub account. You can set up a [free
GitHub account](https://github.com/); here are some
[instructions](https://help.github.com/articles/signing-up-for-a-new-github-account).
3. If you intend to contribute code and/or use the `nigsp` packages
in any way, check that you have `git` and `pip` installed on your
system. Then install the package as a developer. This will let you
run the program with the latest modifications, without requiring to
re-install it every time.
!!! note
The following instructions are provided assuming that python 3 is
**not** your default version of python. If it is, you might need to use
`pip` instead of `pip3`, although some OSs do adopt `pip3` anyway. If
you want to check your OS behaviour, type `python --version` in a terminal.
## Linux, Mac, and Windows developer installation
Be sure to have `git` and `pip` installed. Fork the `nigsp` repository
in GitHub, then open a terminal and run the following code to clone the
forked repository and set it as your *origin*:
```shell
$ git clone https://github.com/{username}/nigsp.git
# or in case you prefer to use ssh:
$ git clone git@github.com:{username}/nigsp.git
```
We also recommend to set up the [`MIPLabCH/nigsp`](https://github.com/MIPLabCH/nigsp) repository as
*upstream*. In this way you can always keep your main branch
up to date with the command *git pull upstream master*:
```shell
$ cd nigsp
$ git remote add upstream https://github.com/MIPLabCH/nigsp.git
$ git pull upstream master
```
## Full developer installation
If it's your first experience as a python developer, or you just want
to be sure that you have everything you need to work on `nigsp`, you
can install it with all the other packages that are frequently
used during development in one step!
Go to the `nigsp` repository folder and execute the command:
```shell
$ cd nigsp
$ pip3 install -e .[dev]
```
This will install:
- `nigsp` as an editable package, which means that you can
modify the program and run it without having to reinstall it every
time!
- All `nigsp` required dependencies.
- All `nigsp` optional dependencies:
+ All packages used for **filetypes I/O** (`pymatreader`, `scipy`, `nibabel`)
+ All packages used for **visualisation and plotting** (`matplotlib`, `nilearn`)
- All **documentation** modules (`mkdocs` based), so that you can
build the docs locally before submitting them.
- All **test** modules (`pytest`, `coverage`), in order for you to test your
code locally before committing it!
- `pre-commit`, for commit hooks.
## Install pre-commit hooks
`pre-commit` is a tool that allows you to _automagically_ run smaller CI operations locally when committing code with git. For instance, it will check for merge conflicts and black the code, improving the quality of your PRs.
Go to the `nigsp` repository folder and execute the command:
```shell
$ cd nigsp
$ pre-commit install
```
To check that pre-commits are correctly installed, run:
```shell
$ pre-commit run --all-files
```
The output should look like:
```
trim trailing whitespace.................................................Passed
fix end of files.........................................................Passed
check yaml...............................................................Passed
check for added large files..............................................Passed
check for case conflicts.................................................Passed
check for merge conflicts................................................Passed
black....................................................................Passed
```
## Check your installation!
Type the commands:
```shell
$ cd nigsp
$ pytest
```
This will execute the tests locally and check that your phys2bids
installation works properly - it should look like this:
```
==================================== test session starts ====================================
platform linux -- Python 3.7.13, pytest-7.1.1, pluggy-1.0.0
rootdir: /home/nemo/Scrivania/gitlab/nigsp, configfile: setup.cfg
plugins: cov-3.0.0
collected 56 items
nigsp/tests/test_graph.py .. [ 3%]
nigsp/tests/test_integration.py . [ 5%]
nigsp/tests/test_io.py .......................... [ 51%]
nigsp/tests/test_nifti.py ........... [ 71%]
nigsp/tests/test_utils.py ................ [100%]
============================== 56 passed in 96.57s (0:01:36) ================================
```
Do **not** worry if there is a xfail error in the log. This happens when
we know that a test will fail for known reasons, and we are probably
working to fix it (see
[here](https://docs.pytest.org/en/latest/skipping.html#xfail-mark-test-functions-as-expected-to-fail)).
However, if you do encounter any other error, check that you are connected to internet, you have all the extra dependencies installed, and their version meets `nigsp`
requirements.