Skip to content

Commit ac96c4b

Browse files
xuyxuxuyxu
committed
doc: update CONTRIBUTING.md
1 parent 124a8f2 commit ac96c4b

1 file changed

Lines changed: 140 additions & 0 deletions

File tree

‎CONTRIBUTING.md‎

Lines changed: 140 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,140 @@
1+
Welcome to the contributing guidelines of torchensemble!
2+
3+
torchensemble is a community-driven project and your contributions are highly welcome. Feel free to [raise an issue](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/issues/new/choose) if you have any problem.
4+
5+
- [Where to contribute](#where-to-contribute)
6+
- [Areas of contribution](#areas-of-contribution)
7+
- [Roadmap](#roadmap)
8+
- [Acknowledging contributions](#acknowledging-contributions)
9+
- [Installation](#installation)
10+
- [Reporting bugs](#reporting-bugs)
11+
- [Continuous integration](#continuous-integration)
12+
- [Unit testing](#unit-testing)
13+
- [Test coverage](#test-coverage)
14+
- [Coding style](#coding-style)
15+
- [API design](#api-design)
16+
- [Documentation](#documentation)
17+
- [Acknowledgement](#acknowledgement)
18+
19+
Where to contribute
20+
-------------------
21+
22+
#### Areas of contribution
23+
24+
We value all kinds of contributions - not just code. The following table gives an overview of key contribution areas.
25+
26+
| Area | Description |
27+
|---------------|--------------------------------------------------------------------------------------------------------------|
28+
| algorithm | collect and report novel algorithms relevant to torchensemble, mainly from top-tier conferences and journals |
29+
| code | implement algorithms, improve or add functionality, fix bugs |
30+
| documentation | improve or add docstrings, user guide, introduction, and experiments |
31+
| testing | report bugs, improve or add unit tests, improve the coverage of unit tests |
32+
| maintenance | improve the development pipeline (continuous integration, Github bots), manage and view issues/pull-requests |
33+
| api design | design interfaces for estimators and other functionality |
34+
35+
### Roadmap
36+
37+
For a more detailed overview of current and future work, check out our [development roadmap](https://ensemble-pytorch.readthedocs.io/en/stable/roadmap.html).
38+
39+
Acknowledging contributions
40+
---------------------------
41+
42+
We follow the [all-contributors specification](https://allcontributors.org) and recognise various types of contributions. Take a look at our past and current [contributors](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/blob/master/CONTRIBUTORS.md)!
43+
44+
If you are a new contributor, please make sure we add you to our list of contributors. All contributions are recorded in [.all-contributorsrc](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/blob/master/.all-contributorsrc).
45+
46+
If we have missed anything, please [raise an issue](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/issues/new/choose) or create a pull request!
47+
48+
Installation
49+
------------
50+
51+
Please visit our [installation instructions](https://ensemble-pytorch.readthedocs.io/en/stable/quick_start.html#installation) to resolve any package issues and dependency errors before they occur in the following steps.
52+
53+
Reporting bugs
54+
--------------
55+
56+
We use GitHub issues to track all bugs and feature requests; feel free to open an issue if you have found a bug or wish to see a feature implemented.
57+
58+
It is recommended to check that your issue complies with the following rules before submitting:
59+
60+
- Verify that your issue is not being currently addressed by other [issues](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/issues) or [pull requests](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/pulls).
61+
- Please ensure all code snippets and error messages are formatted in appropriate code blocks. See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks).
62+
- Please be specific about what estimators and/or functions are involved and the shape of the data, as appropriate; please include a [reproducible](https://stackoverflow.com/help/mcve) code snippet. If an exception is raised, please provide the traceback.
63+
64+
Continuous integration
65+
----------------------
66+
67+
We use continuous integration services on GitHub to automatically check if new pull requests do not break anything and meet code quality standards. Please visit our [config files on continuous integration](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/tree/master/.github/workflows).
68+
69+
### Unit testing
70+
71+
We use [pytest](https://docs.pytest.org/en/latest/) for unit testing. To check if your code passes all tests locally, you need to install the development version of torchensemble and all extra dependencies.
72+
73+
1. Install all extra requirements from the root directory of torchensemble:
74+
75+
```bash
76+
pip install -r build_tools/requirements.txt
77+
```
78+
79+
2. Install the development version of torchensemble:
80+
81+
```bash
82+
pip install -e .
83+
```
84+
85+
3. To run all unit tests, run the following commend from the root directory:
86+
87+
```bash
88+
pytest ./
89+
```
90+
91+
### Test coverage
92+
93+
We use [coverage](https://coverage.readthedocs.io/en/coverage-5.3/) via the [pytest-cov](https://github.com/pytest-dev/pytest-cov) plugin and [codecov](https://codecov.io) to measure and compare test coverage of our code.
94+
95+
Coding style
96+
------------
97+
98+
We follow the [PEP8](https://www.python.org/dev/peps/pep-0008/) coding guidelines. A good example can be found [here](https://gist.github.com/nateGeorge/5455d2c57fb33c1ae04706f2dc4fee01).
99+
100+
We use the [pre-commit](#Code-quality-checks) workflow together with [black](https://black.readthedocs.io/en/stable/) and [flake8](https://flake8.pycqa.org/en/latest/) to automatically apply consistent formatting and check whether your contribution complies with the PEP8 style. Besides, if you are using GitHub desktop on Windows, the following code snippet allows you to format and check the coding style manually.
101+
102+
``` bash
103+
black --skip-string-normalization --config pyproject.toml ./
104+
flake8 --filename=*.py torchensemble/
105+
```
106+
107+
API design
108+
----------
109+
110+
The general API design we follow in torchensemble is similar to [scikit-learn](https://scikit-learn.org/) and [skorch](https://skorch.readthedocs.io/en/latest/?badge=latest).
111+
112+
For docstrings, we use the [numpy docstring standard](https://numpydoc.readthedocs.io/en/latest/format.html\#docstring-standard).
113+
114+
Documentation
115+
-------------
116+
117+
We use [sphinx](https://www.sphinx-doc.org/en/master/) and [readthedocs](https://readthedocs.org/projects/ensemble-pytorch/) to build and deploy our online documentation. You can find our online documentation [here](https://ensemble-pytorch.readthedocs.io).
118+
119+
The source files used to generate the online documentation can be found in [docs/](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/tree/master/docs). For example, the main configuration file for sphinx is [conf.py](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/blob/master/docs/conf.py) and the main page is [index.rst](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/blob/master/docs/index.rst). To add new pages, you need to add a new `.rst` file and include it in the `index.rst` file.
120+
121+
To build the documentation locally, you need to install a few extra dependencies listed in [docs/requirements.txt](https://github.com/TorchEnsemble-Community/Ensemble-Pytorch/blob/master/docs/requirements.txt).
122+
123+
1. Install extra requirements from the root directory, run:
124+
125+
```bash
126+
pip install -r docs/requirements.txt
127+
```
128+
129+
2. To build the website locally, run:
130+
131+
```bash
132+
make html
133+
```
134+
135+
You can find the generated files in the `Ensemble-Pytorch/docs/_build/` folder. To view the website, open `Ensemble-Pytorch/docs/_build/html/index.html` with your preferred web browser.
136+
137+
Acknowledgement
138+
---------------
139+
140+
This CONTRIBUTING is adapted from the [PyTorch](https://github.com/pytorch/pytorch/blob/master/CONTRIBUTING.md) and [Sktime](https://github.com/alan-turing-institute/sktime/blob/main/CONTRIBUTING.md)

0 commit comments

Comments
 (0)