Skip to content

Commit 0cdd591

Browse files
adam2392adam2392
committed
Update contributing guide
Signed-off-by: Adam Li <adam2392@gmail.com>
1 parent b2ca63e commit 0cdd591

26 files changed

+1528
-1
lines changed

‎CONTRIBUTING.md

+138
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,138 @@
1+
# Contributing
2+
3+
Thanks for considering contributing! Please read this document to learn the various ways you can contribute to this project and how to go about doing it.
4+
5+
## Bug reports and feature requests
6+
7+
### Did you find a bug?
8+
9+
First, do [a quick search](https://github.com/py-why/dodiscover/issues) to see whether your issue has already been reported.
10+
If your issue has already been reported, please comment on the existing issue.
11+
12+
Otherwise, open [a new GitHub issue](https://github.com/py-why/dodiscover/issues). Be sure to include a clear title
13+
and description. The description should include as much relevant information as possible. The description should
14+
explain how to reproduce the erroneous behavior as well as the behavior you expect to see. Ideally you would include a
15+
code sample or an executable test case demonstrating the expected behavior.
16+
17+
### Do you have a suggestion for an enhancement or new feature?
18+
19+
We use GitHub issues to track feature requests. Before you create an feature request:
20+
21+
* Make sure you have a clear idea of the enhancement you would like. If you have a vague idea, consider discussing
22+
it first on a GitHub issue.
23+
* Check the documentation to make sure your feature does not already exist.
24+
* Do [a quick search](https://github.com/py-why/dodiscover/issues) to see whether your feature has already been suggested.
25+
26+
When creating your request, please:
27+
28+
* Provide a clear title and description.
29+
* Explain why the enhancement would be useful. It may be helpful to highlight the feature in other libraries.
30+
* Include code examples to demonstrate how the enhancement would be used.
31+
32+
## Making a pull request
33+
34+
When you're ready to contribute code to address an open issue, please follow these guidelines to help us be able to review your pull request (PR) quickly.
35+
36+
1. **Initial setup** (only do this once)
37+
38+
<details><summary>Expand details 👇</summary><br/>
39+
40+
If you haven't already done so, please [fork](https://help.github.com/en/enterprise/2.13/user/articles/fork-a-repo) this repository on GitHub.
41+
42+
Then clone your fork locally with
43+
44+
git clone https://github.com/USERNAME/dodiscover.git
45+
46+
or
47+
48+
git clone git@github.com:USERNAME/dodiscover.git
49+
50+
At this point the local clone of your fork only knows that it came from *your* repo, github.com/USERNAME/dodiscover.git, but doesn't know anything the *main* repo, [https://github.com/py-why/dodiscover.git](https://github.com/py-why/dodiscover). You can see this by running
51+
52+
# Note you should be in the "dodiscover" directory. If you're not
53+
# run "cd ./dodiscover" to change directory into the repo
54+
git remote -v
55+
56+
which will output something like this:
57+
58+
origin https://github.com/USERNAME/dodiscover.git (fetch)
59+
origin https://github.com/USERNAME/dodiscover.git (push)
60+
61+
This means that your local clone can only track changes from your fork, but not from the main repo, and so you won't be able to keep your fork up-to-date with the main repo over time. Therefore you'll need to add another "remote" to your clone that points to [https://github.com/py-why/dodiscover.git](https://github.com/py-why/dodiscover). To do this, run the following:
62+
63+
git remote add upstream https://github.com/py-why/dodiscover.git
64+
65+
Now if you do `git remote -v` again, you'll see
66+
67+
origin https://github.com/USERNAME/dodiscover.git (fetch)
68+
origin https://github.com/USERNAME/dodiscover.git (push)
69+
upstream https://github.com/py-why/dodiscover.git (fetch)
70+
upstream https://github.com/py-why/dodiscover.git (push)
71+
72+
Finally, you'll need to create a Python 3 virtual environment suitable for working on this project. There a number of tools out there that making working with virtual environments easier.
73+
The most direct way is with the [`venv` module](https://docs.python.org/3.7/library/venv.html) in the standard library, but if you're new to Python or you don't already have a recent Python 3 version installed on your machine,
74+
we recommend [Miniconda](https://docs.conda.io/en/latest/miniconda.html).
75+
76+
On Mac, for example, you can install Miniconda with [Homebrew](https://brew.sh/):
77+
78+
brew install miniconda
79+
80+
Then you can create and activate a new Python environment by running:
81+
82+
conda create -n dodiscover python=3.9
83+
conda activate dodiscover
84+
85+
Once your virtual environment is activated, you can install your local clone in "editable mode" with
86+
87+
pip install -U pip setuptools wheel
88+
pip install -e .[dev]
89+
90+
The "editable mode" comes from the `-e` argument to `pip`, and essential just creates a symbolic link from the site-packages directory of your virtual environment to the source code in your local clone. That way any changes you make will be immediately reflected in your virtual environment.
91+
92+
</details>
93+
94+
2. **Ensure your fork is up-to-date**
95+
96+
<details><summary>Expand details 👇</summary><br/>
97+
98+
Once you've added an "upstream" remote pointing to [https://github.com/allenai/python-package-temlate.git](https://github.com/py-why/dodiscover), keeping your fork up-to-date is easy:
99+
100+
git checkout main # if not already on main
101+
git pull --rebase upstream main
102+
git push
103+
104+
</details>
105+
106+
3. **Create a new branch to work on your fix or enhancement**
107+
108+
<details><summary>Expand details 👇</summary><br/>
109+
110+
Committing directly to the main branch of your fork is not recommended. It will be easier to keep your fork clean if you work on a separate branch for each contribution you intend to make.
111+
112+
You can create a new branch with
113+
114+
# replace BRANCH with whatever name you want to give it
115+
git checkout -b BRANCH
116+
git push -u origin BRANCH
117+
118+
</details>
119+
120+
4. **Developing and testing your changes**
121+
122+
<details><summary>Expand details 👇</summary><br/>
123+
124+
Our continuous integration (CI) testing runs [a number of checks](https://github.com/py-why/dodiscover/actions) for each pull request on [GitHub Actions](https://github.com/features/actions). You can run most of these tests locally, which is something you should do *before* opening a PR to help speed up the review process and make it easier for us. Please see our [development guide](https://github.com/py-why/dodiscover/blob/main/DEVELOPING.md) for a comprehensive overview of useful commands leveraging [poetry](https://python-poetry.org). This will cover aspects of code style checking, unit testing, integration testing, and building the documentation. We try to make it as easy as possible with copy/paste commands leveraging poetry which will guide your development process!
125+
126+
And finally, please update the [CHANGELOG](https://github.com/py-why/dodiscover/docs/whats_new.rst) with notes on your contribution in the "Unreleased" section at the top.
127+
128+
After all of the above checks have passed, you can now open [a new GitHub pull request](https://github.com/py-why/dodiscover/pulls).
129+
Make sure you have a clear description of the problem and the solution, and include a link to relevant issues.
130+
131+
We look forward to reviewing your PR!
132+
133+
</details>
134+
135+
### Writing docstrings
136+
137+
We use [Sphinx](https://www.sphinx-doc.org/en/master/index.html) to build our API docs, which automatically parses all docstrings
138+
of public classes and methods. All docstrings should adhere to the [Numpy styling convention](https://www.sphinx-doc.org/en/master/usage/extensions/example_numpy.html).

‎DEVELOPING.md

+43-1
Original file line numberDiff line numberDiff line change
@@ -21,4 +21,46 @@ There are a series of top-level tasks available through Poetry. These can each b
2121

2222
### Docsite
2323
* **start_docs** - start the API documentation site locally
24-
* **build_docs** - build the API documentation site
24+
* **build_docs** - build the API documentation site
25+
26+
For convenience you can run a check for all style components necessary:
27+
28+
make run-checks
29+
30+
This will run isort, black, flake8, mypy, check-manifest, and pydocstyle on the entire repository. Please fix your errors if you see any.
31+
32+
First, you should run [`isort`](https://github.com/PyCQA/isort) and [`black`](https://github.com/psf/black) to make sure you code is formatted consistently.
33+
Many IDEs support code formatters as plugins, so you may be able to setup isort and black to run automatically every time you save.
34+
For example, [`black.vim`](https://github.com/psf/black/tree/master/plugin) will give you this functionality in Vim. But both `isort` and `black` are also easy to run directly from the command line.
35+
Just run this from the root of your clone:
36+
37+
isort .
38+
black .
39+
40+
Our CI also uses [`flake8`](https://github.com/py-why/dodiscover/tree/main/tests) to lint the code base and [`mypy`](http://mypy-lang.org/) for type-checking. You should run both of these next with
41+
42+
flake8 .
43+
44+
and
45+
46+
mypy .
47+
48+
We also strive to maintain high test coverage, so most contributions should include additions to [the unit tests](https://github.com/py-why/dodiscover/tree/main/tests). These tests are run with [`pytest`](https://docs.pytest.org/en/latest/), which you can use to locally run any test modules that you've added or changed.
49+
50+
For example, if you've fixed a bug in `mne_icalabel/a/b.py`, you can run the tests specific to that module with
51+
52+
pytest -v tests/a/b_test.py
53+
54+
Our CI will automatically check that test coverage stays above a certain threshold (around 90%). To check the coverage locally in this example, you could run
55+
56+
pytest -v --cov mne_icalabel.a.b tests/a/b_test.py
57+
58+
If your contribution involves additions to any public part of the API, we require that you write docstrings
59+
for each function, method, class, or module that you add.
60+
See the [Writing docstrings](#writing-docstrings) section below for details on the syntax.
61+
You should test to make sure the API documentation can build without errors by running
62+
63+
cd doc
64+
make html
65+
66+
If the build fails, it's most likely due to small formatting issues. If the error message isn't clear, feel free to comment on this in your pull request.

‎docs/.gitignore

+54
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,54 @@
1+
# build artifacts
2+
3+
.eggs/
4+
.mypy_cache
5+
*.egg-info/
6+
build/
7+
dist/
8+
pip-wheel-metadata/
9+
_build/
10+
generated/
11+
auto_examples
12+
13+
# dev tools
14+
15+
.envrc
16+
.python-version
17+
.idea
18+
.venv/
19+
.vscode/
20+
/*.iml
21+
22+
23+
# jupyter notebooks
24+
25+
.ipynb_checkpoints
26+
27+
28+
# miscellaneous
29+
30+
.cache/
31+
doc/_build/
32+
*.swp
33+
.DS_Store
34+
35+
36+
# python
37+
38+
*.pyc
39+
*.pyo
40+
__pycache__
41+
42+
43+
# testing and continuous integration
44+
45+
.coverage
46+
.pytest_cache/
47+
.benchmarks
48+
49+
# documentation build artifacts
50+
51+
docs/build
52+
site/
53+
54+
test-results

0 commit comments

Comments
 (0)