Skip to content

Commit e32590d

Browse files
janfbjanfb
committed
fix #5: add contribution guide
1 parent 6e6e43a commit e32590d

File tree

2 files changed

+236
-1
lines changed

2 files changed

+236
-1
lines changed

‎CONTRIBUTE.md

+235
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,235 @@
1+
# How to contribute
2+
3+
All contributors are expected to comply with our [Code of Conduct](code_of_conduct.md).
4+
This ensures a positive and inclusive environment for everyone involved.
5+
6+
## User experiences, bugs, and feature requests
7+
8+
If you are using `pyknos`, we would be delighted to know how it worked for you. If it
9+
didn't work according to plan, please open up an
10+
[issue](https://github.com/sbi-dev/pyknos/issues) and tell us more about your use case.
11+
12+
To report bugs and suggest features -- including better documentation --
13+
please equally head over to [issues on GitHub](https://github.com/sbi-dev/pyknos/issues)
14+
and tell us everything.
15+
16+
## Contributing code
17+
18+
Contributions to the `pyknos` package are always welcome! The preferred way to do
19+
it is via pull requests onto our [main repository](https://github.com/sbi-dev/pyknos).
20+
We mention all contributors in the releases.
21+
22+
To avoid duplicated work, we strongly suggest that you take a look at our current [open
23+
issues](https://github.com/sbi-dev/pyknos/issues) and [pull
24+
requests](https://github.com/sbi-dev/pyknos/pulls) to see if someone else is already
25+
doing it. Also, in case you're planning to work on something that has not yet been
26+
proposed by others (e.g. adding a new feature, adding a new example), it is preferable
27+
to first open a new issue explaining what you intend to propose and then working on your
28+
pull request after getting some feedback from others.
29+
30+
### Contribution workflow
31+
32+
The following steps describe all parts of the workflow for doing a contribution such as
33+
installing locally `pyknos` from source, creating a `conda` environment, setting up your
34+
`git` repository, etc. We've taken strong inspiration from the contribution guides for
35+
[`scikit-learn`](https://scikit-learn.org/stable/developers/contributing.html) and
36+
[`mne`](https://mne.tools/stable/development/contributing.html):
37+
38+
**Step 1**: [Create an account](https://github.com/) on GitHub if you do not
39+
already have one.
40+
41+
**Step 2**: Fork the [project repository](https://github.com/sbi-dev/pyknos): click
42+
on the ‘Fork’ button near the top of the page. This will create a copy of the
43+
`pyknos` codebase under your GitHub user account. See more details on how to fork
44+
a repository [here](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo).
45+
46+
**Step 3**: Clone your fork of the `pyknos` repo from your GitHub account to your
47+
local disk:
48+
49+
```bash
50+
git clone git@github.com:$USERNAME/sbi.git
51+
cd sbi
52+
```
53+
54+
**Step 4**: Install a recent version of Python (we currently recommend 3.10)
55+
for instance using [`miniforge`](https://github.com/conda-forge/miniforge). We
56+
strongly recommend you create a specific `conda` environment for doing
57+
development on `pyknos` as per:
58+
59+
```bash
60+
conda create -n sbi_dev python=3.10
61+
conda activate sbi_dev
62+
```
63+
64+
**Step 5**: Install `pyknos` in editable mode with
65+
66+
```bash
67+
pip install -e ".[dev]"
68+
```
69+
70+
This installs the `pyknos` package into the current environment by creating a link to
71+
the source code directory (instead of copying the code to pip's `site_packages`
72+
directory, which is what normally happens). This means that any edits you make to the
73+
`pyknos` source code will be reflected the next time you open a Python interpreter and
74+
`import pyknos` (the `-e` flag of pip stands for an “editable” installation, and the
75+
`dev` flag installs development and testing dependencies). This requires at least Python
76+
3.8.
77+
78+
**Step 6**: Add the upstream remote. This saves a reference to the main `pyknos`
79+
repository, which you can use to keep your repository synchronized with the latest
80+
changes:
81+
82+
```bash
83+
git remote add upstream git@github.com:sbi-dev/pyknos.git
84+
```
85+
86+
Check that the upstream and origin remote aliases are configured correctly by running
87+
`git remote -v` which should display:
88+
89+
```bash
90+
origin git@github.com:$USERNAME/pyknos.git (fetch)
91+
origin git@github.com:$USERNAME/pyknos.git (push)
92+
upstream git@github.com:sbi-dev/pyknos.git (fetch)
93+
upstream git@github.com:sbi-dev/pyknos.git (push)
94+
```
95+
96+
**Step 7**: Install `pre-commit` to run code style checks before each commit:
97+
98+
```bash
99+
pip install pre-commit
100+
pre-commit install
101+
```
102+
103+
You should now have a working installation of `pyknos` and a git repository properly
104+
configured for making contributions. The following steps describe the process of
105+
modifying code and submitting a pull request:
106+
107+
**Step 8**: Synchronize your main branch with the upstream/main branch. See more details
108+
on [GitHub
109+
Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/syncing-a-fork):
110+
111+
```bash
112+
git checkout main
113+
git fetch upstream
114+
git merge upstream/main
115+
```
116+
117+
**Step 9**: Create a feature branch to hold your development changes:
118+
119+
```bash
120+
git checkout -b my_feature
121+
```
122+
123+
and start making changes. Always use a feature branch! It’s good practice to never work
124+
on the main branch, as this allows you to easily get back to a working state of the code
125+
if needed (e.g., if you’re working on multiple changes at once, or need to pull in
126+
recent changes from someone else to get your new feature to work properly). In most
127+
cases, you should make PRs into the upstream’s main branch.
128+
129+
**Step 10**: Develop your code on your feature branch on the computer, using
130+
Git to do the version control. When you’re done editing, add changed files
131+
using `git add` and then `git commit` to record your changes:
132+
133+
```bash
134+
git add modified_files
135+
git commit -m "description of your commit"
136+
```
137+
138+
Then push the changes to your GitHub account with:
139+
140+
```bash
141+
git push -u origin my_feature
142+
```
143+
144+
The `-u` flag ensures that your local branch will be automatically linked with the
145+
remote branch, so you can later use `git push` and `git pull` without any extra
146+
arguments.
147+
148+
**Step 11**: Follow
149+
[these](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork)
150+
instructions to create a pull request from your fork. This will send a notification to
151+
`pyknos` maintainers and trigger reviews and comments regarding your contribution.
152+
153+
It is often helpful to keep your local feature branch synchronized with the latest
154+
changes of the main `pyknos` repository:
155+
156+
```bash
157+
git fetch upstream
158+
git merge upstream/main
159+
```
160+
161+
### Style conventions and testing
162+
163+
All our docstrings and comments are written following the [Google
164+
Style](http://google.github.io/styleguide/pyguide.html#38-comments-and-docstrings).
165+
166+
For code linting and formatting, we use [`ruff`](https://docs.astral.sh/ruff/), which is
167+
installed alongside `pyknos`.
168+
169+
You can exclude slow tests and those which require a GPU with
170+
171+
```bash
172+
pytest -m "not slow and not gpu"
173+
```
174+
175+
Additionally, we recommend to run tests with
176+
177+
```bash
178+
pytest -n auto -m "not slow and not gpu"
179+
```
180+
181+
in parallel. GPU tests should probably not be run this way. If you see unexpected
182+
behavior (tests fail if they shouldn't), try to run them without `-n auto` and
183+
see if it persists. When writing new tests and debugging things, it may make sense
184+
to also run them without `-n auto`.
185+
186+
When you create a PR onto `main`, our Continuous Integration (CI) actions on
187+
GitHub will perform the following checks:
188+
189+
- **`ruff`** for linting and formatting (including `black`, `isort`, and `flake8`)
190+
- **[`pyright`](https://github.com/Microsoft/pyright)** for static type checking.
191+
- **`pytest`** for running a subset of fast tests from our test suite.
192+
193+
If any of these fail, try reproducing and solving the error locally:
194+
195+
- **`ruff`**: Make sure you have `pre-commit` installed locally with the same version as
196+
specified in the [requirements](pyproject.toml). Execute it using `pre-commit run
197+
--all-files`. `ruff` tends to give informative error messages that help you fix the
198+
problem. Note that pre-commit only detects problems with `ruff` linting and
199+
formatting, but does not fix them. You can fix them either by running `ruff check .
200+
--fix` (linting), followed by `ruff format .`(formatting), or by hand.
201+
- **`pyright`**: Run it locally using `pyright sbi/` and ensure you are using the same
202+
`pyright` version as used in the CI (which is the case if you have installed it with
203+
`pip install -e ".[dev]"` but note that you have to rerun it once someone updates the
204+
version in the `pyproject.toml`).
205+
- Known issues and fixes:
206+
- If using `**kwargs`, you either have to specify all possible types of `kwargs`,
207+
e.g. `**kwargs: Union[int, boolean]` or use `**kwargs: Any`
208+
209+
- **`pytest`**: On GitHub Actions you can see which test failed. Reproduce it locally,
210+
e.g., using `pytest -n auto tests/linearGaussian_snpe_test.py`. Note that this will run
211+
for a few minutes and should result in passes and expected fails (xfailed).
212+
- Commit and push again until CI tests pass. Don't hesitate to ask for help by
213+
commenting on the PR.
214+
215+
## Contributing to the documentation
216+
217+
Most of the documentation for `pyknos` is written in markdown and the website is
218+
generated using `mkdocs` with `mkdocstrings`. To work on improvements of the
219+
documentation, you should first run the command on your terminal
220+
221+
```bash
222+
mkdocs serve
223+
```
224+
225+
and open a browser on the page proposed by `mkdocs`. Now, whenever you make changes to
226+
the markdown files of the documentation, you can see the results almost immediately in
227+
the browser.
228+
229+
Note that the tutorials and examples are initially written in jupyter notebooks and then
230+
converted to markdown programatically. To do so locally, you should run
231+
232+
```bash
233+
jupyter nbconvert --to markdown ../tutorials/*.ipynb --output-dir docs/tutorial/
234+
jupyter nbconvert --to markdown ../examples/*.ipynb --output-dir docs/examples/
235+
```

‎README.md

+1-1
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[![PyPI version](https://badge.fury.io/py/pyknos.svg)](https://badge.fury.io/py/pyknos)
2-
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/mackelab/sbi/blob/master/CONTRIBUTING.md)
2+
[![Contributions welcome](https://img.shields.io/badge/contributions-welcome-brightgreen.svg?style=flat)](https://github.com/sbi-dev/pyknos/blob/master/CONTRIBUTING.md)
33
[![GitHub license](https://img.shields.io/github/license/mackelab/pyknos)](https://github.com/mackelab/sbi/blob/master/LICENSE.txt)
44

55
## Description

0 commit comments

Comments
 (0)