10000 Revert "DOC Shorten and improve CONTRIBUTING.md (#12801)" · xhluca/scikit-learn@d616ab7 · GitHub
[go: up one dir, main page]
Skip to content

Commit d616ab7

Browse files
author
Xing
authored
Revert "DOC Shorten and improve CONTRIBUTING.md (scikit-learn#12801)"
This reverts commit 9d8cdf1.
1 parent 6629d39 commit d616ab7

File tree

2 files changed

+277
-85
lines changed

2 files changed

+277
-85
lines changed

‎CONTRIBUTING.md

Lines changed: 244 additions & 38 deletions
Original file line numberDiff line numberDiff line change
@@ -2,41 +2,247 @@
22
Contributing to scikit-learn
33
============================
44

5-
There are many ways to contribute to scikit-learn, with the most common ones
6-
being contribution of code or documentation to the project. Improving the
7-
documentation is no less important than improving the library itself. If you
8-
find a typo in the documentation, or have made improvements, do not hesitate to
9-
send an email to the mailing list or preferably submit a GitHub pull request.
10-
Documentation can be found under the
11-
[doc/](https://github.com/scikit-learn/scikit-learn/tree/master/doc) directory.
12-
13-
But there are many other ways to help. In particular answering queries on the
14-
[issue tracker](https://github.com/scikit-learn/scikit-learn/issues),
15-
investigating bugs, and [reviewing other developers' pull
16-
requests](http://scikit-learn.org/dev/developers/contributing.html#code-review-guidelines)
17-
are very valuable contributions that decrease the burden on the project
18-
maintainers.
19-
20-
Another way to contribute is to report issues you're facing, and give a "thumbs
21-
up" on issues that others reported and that are relevant to you. It also helps
22-
us if you spread the word: reference the project from your blog and articles,
23-
link to it from your website, or simply star it in GitHub to say "I use it".
24-
25-
Guideline
26-
---------
27-
28-
Full contribution guidelines are available in the repository at
29-
`doc/developers/contributing.rst`, or online at:
30-
31-
http://scikit-learn.org/dev/developers/contributing.html
32-
33-
Quick links to:
34-
* [Submitting a bug report or feature request](http://scikit-learn.org/dev/developers/contributing.html#submitting-a-bug-report-or-a-feature-request)
35-
* [Contributing code](http://scikit-learn.org/dev/developers/contributing.html#contributing-code)
36-
* [Coding guidelines](http://scikit-learn.org/dev/developers/contributing.html#coding-guidelines)
37-
38-
Code of Conduct
39-
---------------
40-
41-
We abide by the principles of openness, respect, and consideration of others
42-
of the Python Software Foundation: https://www.python.org/psf/codeofconduct/.
5+
**Note: This document is a 'getting started' summary for contributing code,
6+
documentation, testing, and filing issues.** Visit the [**Contributing
7+
page**](http://scikit-learn.org/dev/developers/contributing.html)
8+
for the full contributor's guide. Please read it carefully to help make
9+
the code review process go as smoothly as possible and maximize the
10+
likelihood of your contribution being merged.
11+
12+
How to contribute
13+
-----------------
14+
15+
The preferred workflow for contributing to scikit-learn is to fork the
16+
[main repository](https://github.com/scikit-learn/scikit-learn) on
17+
GitHub, clone, and develop on a branch. Steps:
18+
19+
1. Fork the [project repository](https://github.com/scikit-learn/scikit-learn)
20+
by clicking on the 'Fork' button near the top right of the page. This creates
21+
a copy of the code under your GitHub user account. For more details on
22+
how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/).
23+
24+
2. Clone your fork of the scikit-learn repo from your GitHub account to your local disk:
25+
26+
```bash
27+
$ git clone git@github.com:YourLogin/scikit-learn.git
28+
$ cd scikit-learn
29+
```
30+
31+
3. Create a ``feature`` branch to hold your development changes:
32+
33+
```bash
34+
$ git checkout -b my-feature
35+
```
36+
37+
Always use a ``feature`` branch. It's good practice to never work on the ``master`` branch!
38+
39+
4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files:
40+
41+
```bash
42+
$ git add modified_files
43+
$ git commit
44+
```
45+
46+
to record your changes in Git, then push the changes to your GitHub account with:
47+
48+
```bash
49+
$ git push -u origin my-feature
50+
```
51+
52+
5. Follow [these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork)
53+
to create a pull request from your fork. This will send an email to the committers.
54+
55+
(If any of the above seems like magic to you, please look up the
56+
[Git documentation](https://git-scm.com/documentation) on the web, or ask a friend or another contributor for help.)
57+
58+
Pull Request Checklist
59+
----------------------
60+
61+
We recommended that your contribution complies with the
62+
following rules before you submit a pull request:
63+
64+
- Follow the
65+
[coding-guidelines](http://scikit-learn.org/dev/developers/contributing.html#coding-guidelines).
66+
67+
- Use, when applicable, the validation tools and scripts in the
68+
`sklearn.utils` submodule. A list of utility routines available
69+
for developers can be found in the
70+
[Utilities for Developers](http://scikit-learn.org/dev/developers/utilities.html#developers-utils)
71+
page.
72+
73+
- Give your pull request a helpful title that summarises what your
74+
contribution does. In some cases `Fix <ISSUE TITLE>` is enough.
75+
`Fix #<ISSUE NUMBER>` is not enough.
76+
77+
- Often pull requests resolve one or more other issues (or pull requests).
78+
If merging your pull request means that some other issues/PRs should
79+
be closed, you should
80+
[use keywords to create link to them](https://github.com/blog/1506-closing-issues-via-pull-requests/)
81+
(e.g., `Fixes #1234`; multiple issues/PRs are allowed as long as each one
82+
is preceded by a keyword). Upon merging, those issues/PRs will
83+
automatically be closed by GitHub. If your pull request is simply related
84+
to some other issues/PRs, create a link to them without using the keywords
85+
(e.g., `See also #1234`).
86+
87+
- All public methods should have informative docstrings with sample
88+
usage presented as doctests when appropriate.
89+
90+
- Please prefix the title of your pull request with `[MRG]` (Ready for
91+
Merge), if the contribution is complete and ready for a detailed review.
92+
Two core developers will review your code and change the prefix of the pull
93+
request to `[MRG + 1]` and `[MRG + 2]` on approval, making it eligible
94+
for merging. An incomplete contribution -- where you expect to do more work before
95+
receiving a full review -- should be prefixed `[WIP]` (to indicate a work
96+
in progress) and changed to `[MRG]` when it matures. WIPs may be useful
97+
to: indicate you are working on something to avoid duplicated work,
98+
request broad review of functionality or API, or seek collaborators.
99+
WIPs often benefit from the inclusion of a
100+
[task list](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments)
101+
in the PR description.
102+
103+
- All other tests pass when everything is rebuilt from scratch. On
104+
Unix-like systems, check with (from the toplevel source folder):
105+
106+
```bash
107+
$ make
108+
```
109+
110+
- When adding additional functionality, provide at least one
111+
example script in the ``examples/`` folder. Have a look at other
112+
examples for reference. Examples should demonstrate why the new
113+
functionality is useful in practice and, if possible, compare it
114+
to other methods available in scikit-learn.
115+
116+
- Documentation and high-coverage tests are necessary for enhancements to be
117+
accepted. Bug-fixes or new features should be provided with
118+
[non-regression tests](https://en.wikipedia.org/wiki/Non-regression_testing).
119+
These tests verify the correct behavior of the fix or feature. In this
120+
manner, further modifications on the code base are granted to be consistent
121+
with the desired behavior.
122+
For the Bug-fixes case, at the time of the PR, this tests should fail for
123+
the code base in master and pass for the PR code.
124+
125+
126+
- At least one paragraph of narrative documentation with links to
127+
references in the literature (with PDF links when possible) and
128+
the example.
129+
130+
- The documentation should also include expected time and space
131+
complexity of the algorithm and scalability, e.g. "this algorithm
132+
can scale to a large number of samples > 100000, but does not
133+
scale in dimensionality: n_features is expected to be lower than
134+
100".
135+
136+
You can also check for common programming errors with the following
137+
tools:
138+
139+
- Code with good unittest **coverage** (at least 80%), check with:
140+
141+
```bash
142+
$ pip install pytest pytest-cov
143+
$ pytest --cov sklearn path/to/tests_for_package
144+
```
145+
146+
- No flake8 warnings, check with:
147+
148+
```bash
149+
$ pip install flake8
150+
$ flake8 path/to/module.py
151+
```
152+
153+
Bonus points for contributions that include a performance analysis with
154+
a benchmark script and profiling output (please report on the mailing
155+
list or on the GitHub issue).
156+
157+
Filing bugs
158+
-----------
159+
We use GitHub issues to track all bugs and feature requests; feel free to
160+
open an issue if you have found a bug or wish to see a feature implemented.
161+
162+
It is recommended to check that your issue complies with the
163+
following rules before submitting:
164+
165+
- Verify that your issue is not being currently addressed by other
166+
[issues](https://github.com/scikit-learn/scikit-learn/issues?q=)
167+
or [pull requests](https://github.com/scikit-learn/scikit-learn/pulls?q=).
168+
169+
- If you are submitting an algorithm or feature request, please verify that
170+
the algorithm fulfills our
171+
[new algorithm requirements](http://scikit-learn.org/dev/faq.html#what-are-the-inclusion-criteria-for-new-algorithms).
172+
173+
- Please ensure all code snippets and error messages are formatted in
174+
appropriate code blocks.
175+
See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks).
176+
177+
- Please include your operating system type and version number, as well
178+
as your Python, scikit-learn, numpy, and scipy versions. This information
179+
can be found by running the following code snippet:
180+
181+
For scikit-learn >= 0.20:
182+
183+
```python
184+
import sklearn; sklearn.show_versions()
185+
```
186+
187+
For scikit-learn < 0.20:
188+
189+
```python
190+
import platform; print(platform.platform())
191+
import sys; print("Python", sys.version)
192+
import numpy; print("NumPy", numpy.__version__)
193+
import scipy; print("SciPy", scipy.__version__)
194+
import sklearn; print("Scikit-Learn", sklearn.__version__)
195+
```
196+
197+
- Please be specific about what estimators and/or functions are involved
198+
and the shape of the data, as appropriate; please include a
199+
[reproducible](https://stackoverflow.com/help/mcve) code snippet
200+
or link to a [gist](https://gist.github.com). If an exception is raised,
201+
please provide the traceback.
202+
203+
New contributor tips
204+
--------------------
205+
206+
A great way to start contributing to scikit-learn is to pick an item from the
207+
list of
208+
[good first issues](https://github.com/scikit-learn/scikit-learn/labels/good%20first%20issue). If
209+
you have already contributed to scikit-learn look at
210+
[Easy issues](https://github.com/scikit-learn/scikit-learn/labels/Easy)
211+
instead. Resolving these issues allow you to start contributing to the project
212+
without much prior knowledge. Your assistance in this area will be greatly
213+
appreciated by the more experienced developers as it helps free up their time to
214+
concentrate on other issues.
215+
216+
Documentation
217+
-------------
218+
219+
We are glad to accept any sort of documentation: function docstrings,
220+
reStructuredText documents (like this one), tutorials, etc.
221+
reStructuredText documents live in the source code repository under the
222+
doc/ directory.
223+
224+
You can edit the documentation using any text editor and then generate
225+
the HTML output by typing ``make html`` from the doc/ directory.
226+
Alternatively, ``make`` can be used to quickly generate the
227+
documentation without the example gallery. The resulting HTML files will
228+
be placed in ``_build/html/stable`` and are viewable in a web browser. See the
229+
``README`` file in the ``doc/`` directory for more information.
230+
231+
For building the documentation, you will need
232+
[sphinx](http://sphinx.pocoo.org/),
233+
[matplotlib](https://matplotlib.org/), and
234+
[pillow](https://pillow.readthedocs.io/en/latest/).
235+
236+
When you are writing documentation, it is important to keep a good
237+
compromise between mathematical and algorithmic details, and give
238+
intuition to the reader on what the algorithm does. It is best to always
239+
start with a small paragraph with a hand-waving explanation of what the
240+
method does to the data and a figure (coming from an example)
241+
illustrating it.
242+
243+
Further Information
244+
-------------------
245+
246+
Visit the [Contributing Code](http://scikit-learn.org/stable/developers/contributing.html#coding-guidelines)
247+
section of the website for more information including conforming to the
248+
API spec and profiling contributed code.

0 commit comments

Comments
 (0)
0