Skip to content

Contributing #12215

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Closed
wants to merge 2 commits into from
Closed

Contributing #12215

Changes from all commits
Commits
Show all changes
2 commits
Select commit Hold shift + click to select a range
3ec525d
edits
eharris99 Sep 29, 2018
09cc655
edits 2
eharris99 Sep 29, 2018
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
102 changes: 41 additions & 61 deletions CONTRIBUTING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,105 +2,97 @@
Contributing to scikit-learn
============================

**Note: This document is a 'getting started' summary for contributing code,
documentation, testing, and filing issues.** Visit the [**Contributing
**Note: This document is a quick overview of open source contribution.** Visit the official [**Contributing
page**](http://scikit-learn.org/dev/developers/contributing.html)
for the full contributor's guide. Please read it carefully to help make
the code review process go as smoothly as possible and maximize the
likelihood of your contribution being merged.
for more comprehensive instructions. Read carefully to increase your chances for a merged pull request.

How to contribute
-----------------

The preferred workflow for contributing to scikit-learn is to fork the
[main repository](https://github.com/scikit-learn/scikit-learn) on
GitHub, clone, and develop on a branch. Steps:
To contribute to scikit-learn, fork the
[main GitHub repository](https://github.com/scikit-learn/scikit-learn)
, clone, and develop on a new branch. Steps:

1. Fork the [project repository](https://github.com/scikit-learn/scikit-learn)
by clicking on the 'Fork' button near the top right of the page. This creates
a copy of the code under your GitHub user account. For more details on
how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/).
by clicking on the 'Fork' button near the top right of the repo page. This creates
a copy of scikit-learn on your GitHub account. For more details on forking, see [this guide](https://help.github.com/articles/fork-a-repo/).

2. Clone your fork of the scikit-learn repo from your GitHub account to your local disk:
2. Clone your fork of scikit-learn to your local disk:

```bash
$ git clone git@github.com:YourLogin/scikit-learn.git
$ cd scikit-learn
```

3. Create a ``feature`` branch to hold your development changes:
3. Create a ``feature`` branch within your clone:

```bash
$ git checkout -b my-feature
```

Always use a ``feature`` branch. It's good practice to never work on the ``master`` branch!
Always use a ``feature`` branch. Don't work on the ``master`` branch!

4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files:
4. Develop the feature on the branch. Add changed files using ``git add``, and then ``git commit`` files:

```bash
$ git add modified_files
$ git commit
```

to record your changes in Git, then push the changes to your GitHub account with:
to record your changes in Git. Then push the changes up to your GitHub account with:

```bash
$ git push -u origin my-feature
```

5. Follow [these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork)
to create a pull request from your fork. This will send an email to the committers.
to create a pull request from your fork. The project maintainers will receive an email about your pull request.

(If any of the above seems like magic to you, please look up the
[Git documentation](https://git-scm.com/documentation) on the web, or ask a friend or another contributor for help.)
(If any of the above is confusing, please read the
[Git documentation](https://git-scm.com/documentation), or ask a friend or another contributor for help.)

Pull Request Checklist
----------------------

We recommended that your contribution complies with the
following rules before you submit a pull request:
We recommended that your contribution comply with these
important rules before you submit a pull request:

- Follow the
[coding-guidelines](http://scikit-learn.org/dev/developers/contributing.html#coding-guidelines).

- Use, when applicable, the validation tools and scripts in the
`sklearn.utils` submodule. A list of utility routines available
for developers can be found in the
[Utilities for Developers](http://scikit-learn.org/dev/developers/utilities.html#developers-utils)
`sklearn.utils` submodule. A list of available utility routines can be found [here](http://scikit-learn.org/dev/developers/utilities.html#developers-utils)
page.

- Give your pull request a helpful title that summarises what your
contribution does. In some cases `Fix <ISSUE TITLE>` is enough.
- Give your pull request a helpful title that summarises your
contribution. In some cases `Fix <ISSUE TITLE>` is enough.
`Fix #<ISSUE NUMBER>` is not enough.

- Often pull requests resolve one or more other issues (or pull requests).
- Often pull requests resolve other issues (or pull requests).
If merging your pull request means that some other issues/PRs should
be closed, you should
[use keywords to create link to them](https://github.com/blog/1506-closing-issues-via-pull-requests/)
[use keywords to link to them](https://github.com/blog/1506-closing-issues-via-pull-requests/)
(e.g., `Fixes #1234`; multiple issues/PRs are allowed as long as each one
is preceded by a keyword). Upon merging, those issues/PRs will
automatically be closed by GitHub. If your pull request is simply related
is preceded by a keyword). Upon merging, GitHub will automatically close those issues/PRs. If your pull request is simply related
to some other issues/PRs, create a link to them without using the keywords
(e.g., `See also #1234`).

- All public methods should have informative docstrings with sample
usage presented as doctests when appropriate.

- Please prefix the title of your pull request with `[MRG]` (Ready for
- Prefix the title of your pull request with `[MRG]` (Ready for
Merge), if the contribution is complete and ready for a detailed review.
Two core developers will review your code and change the prefix of the pull
request to `[MRG + 1]` and `[MRG + 2]` on approval, making it eligible
for merging. An incomplete contribution -- where you expect to do more work before
receiving a full review -- should be prefixed `[WIP]` (to indicate a work
in progress) and changed to `[MRG]` when it matures. WIPs may be useful
to: indicate you are working on something to avoid duplicated work,
request broad review of functionality or API, or seek collaborators.
to: (1) indicate you are working on something to avoid duplicated work, (2) request broad review of functionality or API, or (3) seek collaborators.
WIPs often benefit from the inclusion of a
[task list](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments)
in the PR description.

- All other tests pass when everything is rebuilt from scratch. On
- Confirm that all other tests pass when everything is rebuilt from scratch. On
Unix-like systems, check with (from the toplevel source folder):

```bash
Expand All @@ -113,28 +105,21 @@ following rules before you submit a pull request:
functionality is useful in practice and, if possible, compare it
to other methods available in scikit-learn.

- Documentation and high-coverage tests are necessary for enhancements to be
accepted. Bug-fixes or new features should be provided with
- Confirm that tests pass in the code of your pull request but fail in the codebase. Bug-fixes or new features should be provided with
[non-regression tests](https://en.wikipedia.org/wiki/Non-regression_testing).
These tests verify the correct behavior of the fix or feature. In this
manner, further modifications on the code base are granted to be consistent
These tests verify the correct behavior of the fix or feature. This way, further modifications on the code base will be consistent
with the desired behavior.
For the Bug-fixes case, at the time of the PR, this tests should fail for
the code base in master and pass for the PR code.


- At least one paragraph of narrative documentation with links to
- Add at least one paragraph of narrative documentation with links to
references in the literature (with PDF links when possible) and
the example.

- The documentation should also include expected time and space
complexity of the algorithm and scalability, e.g. "this algorithm
- Include expected time and space complexity of the algorithm and scalability in the documentation. E.g. "this algorithm
can scale to a large number of samples > 100000, but does not
scale in dimensionality: n_features is expected to be lower than
100".

You can also check for common programming errors with the following
tools:
You can also check for common programming errors with tools:

- Code with good unittest **coverage** (at least 80%), check with:

Expand All @@ -143,7 +128,7 @@ tools:
$ pytest --cov sklearn path/to/tests_for_package
```

- No flake8 warnings, check with:
- Check that there are no flake8 warnings:

```bash
$ pip install flake8
Expand All @@ -156,25 +141,22 @@ list or on the GitHub issue).

Filing bugs
-----------
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.
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.

It is recommended to check that your issue complies with the
following rules before submitting:
Check that your issue complies with the following rules:

- Verify that your issue is not being currently addressed by other
- Your issue should not being currently addressed by other
[issues](https://github.com/scikit-learn/scikit-learn/issues?q=)
or [pull requests](https://github.com/scikit-learn/scikit-learn/pulls?q=).

- If you are submitting an algorithm or feature request, please verify that
the algorithm fulfills our
- If you are submitting an algorithm or feature request, verify that the algorithm fulfills our
[new algorithm requirements](http://scikit-learn.org/dev/faq.html#what-are-the-inclusion-criteria-for-new-algorithms).

- Please ensure all code snippets and error messages are formatted in
- 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).

- Please include your operating system type and version number, as well
- Include your operating system type and version number, as well
as your Python, scikit-learn, numpy, and scipy versions. This information
can be found by running the following code snippet:

Expand All @@ -186,7 +168,7 @@ following rules before submitting:
import sklearn; print("Scikit-Learn", sklearn.__version__)
```

- Please be specific about what estimators and/or functions are involved
- Be specific about what estimators and/or functions are involved
and the shape of the data, as appropriate; please include a
[reproducible](http://stackoverflow.com/help/mcve) code snippet
or link to a [gist](https://gist.github.com). If an exception is raised,
Expand All @@ -195,15 +177,13 @@ following rules before submitting:
New contributor tips
--------------------

A great way to start contributing to scikit-learn is to pick an item from the
list of
A great way to start contributing to scikit-learn is to pick an item from the list of
[good first issues](https://github.com/scikit-learn/scikit-learn/labels/good%20first%20issue). If
you have already contributed to scikit-learn look at
[Easy issues](https://github.com/scikit-learn/scikit-learn/labels/Easy)
instead. Resolving these issues allow you to start contributing to the project
without much prior knowledge. Your assistance in this area will be greatly
appreciated by the more experienced developers as it helps free up their time to
concentrate on other issues.
appreciated by the more experienced developers, as it helps free up their time to concentrate on other issues.

Documentation
-------------
Expand Down