|
| 1 | +How to contribute |
| 2 | +----------------- |
| 3 | + |
| 4 | +The preferred workflow for contributing to the OpenML python connector is to |
| 5 | +fork the [main repository](https://github.com/openml/openml-python) on |
| 6 | +GitHub, clone, check out the branch `develop`, and develop on a new branch |
| 7 | +branch. Steps: |
| 8 | + |
| 9 | +1. Fork the [project repository](https://github.com/openml/openml-python) |
| 10 | + by clicking on the 'Fork' button near the top right of the page. This creates |
| 11 | + a copy of the code under your GitHub user account. For more details on |
| 12 | + how to fork a repository see [this guide](https://help.github.com/articles/fork-a-repo/). |
| 13 | + |
| 14 | +2. Clone your fork of the openml-python repo from your GitHub account to your |
| 15 | +local disk: |
| 16 | + |
| 17 | + ```bash |
| 18 | + $ git clone [email protected]:YourLogin/openml-python.git |
| 19 | + $ cd openml-python |
| 20 | + ``` |
| 21 | + |
| 22 | +3. Swith to the ``develop`` branch: |
| 23 | + |
| 24 | + ```bash |
| 25 | + $ git checkout develop |
| 26 | + ``` |
| 27 | + |
| 28 | +3. Create a ``feature`` branch to hold your development changes: |
| 29 | + |
| 30 | + ```bash |
| 31 | + $ git checkout -b feature/my-feature |
| 32 | + ``` |
| 33 | + |
| 34 | + Always use a ``feature`` branch. It's good practice to never work on the ``master`` or ``develop`` branch! To make the nature of your pull request easily visible, please perpend the name of the branch with the type of changes you want to merge, such as ``feature`` if it contains a new feature, ``fix`` for a bugfix, ``doc`` for documentation and ``maint`` for other maintenance on the package. |
| 35 | + |
| 36 | +4. Develop the feature on your feature branch. Add changed files using ``git add`` and then ``git commit`` files: |
| 37 | + |
| 38 | + ```bash |
| 39 | + $ git add modified_files |
| 40 | + $ git commit |
| 41 | + ``` |
| 42 | + |
| 43 | + to record your changes in Git, then push the changes to your GitHub account with: |
| 44 | + |
| 45 | + ```bash |
| 46 | + $ git push -u origin my-feature |
| 47 | + ``` |
| 48 | + |
| 49 | +5. Follow [these instructions](https://help.github.com/articles/creating-a-pull-request-from-a-fork) |
| 50 | +to create a pull request from your fork. This will send an email to the committers. |
| 51 | + |
| 52 | +(If any of the above seems like magic to you, please look up the |
| 53 | +[Git documentation](https://git-scm.com/documentation) on the web, or ask a friend or another contributor for help.) |
| 54 | + |
| 55 | +Pull Request Checklist |
| 56 | +---------------------- |
| 57 | + |
| 58 | +We recommended that your contribution complies with the |
| 59 | +following rules before you submit a pull request: |
| 60 | + |
| 61 | +- Follow the |
| 62 | + [pep8 style guilde](https://www.python.org/dev/peps/pep-0008/). |
| 63 | + |
| 64 | +- If your pull request addresses an issue, please use the pull request title |
| 65 | + to describe the issue and mention the issue number in the pull request description. This will make sure a link back to the original issue is |
| 66 | + created. |
| 67 | + |
| 68 | +- An incomplete contribution -- where you expect to do more work before |
| 69 | + receiving a full review -- should be prefixed `[WIP]` (to indicate a work |
| 70 | + in progress) and changed to `[MRG]` when it matures. WIPs may be useful |
| 71 | + to: indicate you are working on something to avoid duplicated work, |
| 72 | + request broad review of functionality or API, or seek collaborators. |
| 73 | + WIPs often benefit from the inclusion of a |
| 74 | + [task list](https://github.com/blog/1375-task-lists-in-gfm-issues-pulls-comments) |
| 75 | + in the PR description. |
| 76 | + |
| 77 | +- All tests pass when running `nosetests`. On |
| 78 | + Unix-like systems, check with (from the toplevel source folder): |
| 79 | + |
| 80 | + ```bash |
| 81 | + $ nosetests |
| 82 | + ``` |
| 83 | + |
| 84 | + For Windows systems, execute the command from an Anaconda Prompt or add `nosetests` to PATH before executing the command. |
| 85 | + |
| 86 | +- Documentation and high-coverage tests are necessary for enhancements to be |
| 87 | + accepted. Bug-fixes or new features should be provided with |
| 88 | + [non-regression tests](https://en.wikipedia.org/wiki/Non-regression_testing). |
| 89 | + These tests verify the correct behavior of the fix or feature. In this |
| 90 | + manner, further modifications on the code base are granted to be consistent |
| 91 | + with the desired behavior. |
| 92 | + For the Bug-fixes case, at the time of the PR, this tests should fail for |
| 93 | + the code base in develop and pass for the PR code. |
| 94 | + |
| 95 | + |
| 96 | +You can also check for common programming errors with the following |
| 97 | +tools: |
| 98 | + |
| 99 | +- Code with good unittest **coverage** (at least 80%), check with: |
| 100 | + |
| 101 | + ```bash |
| 102 | + $ pip install nose coverage |
| 103 | + $ nosetests --with-coverage path/to/tests_for_package |
| 104 | + ``` |
| 105 | + |
| 106 | +- No pyflakes warnings, check with: |
| 107 | + |
| 108 | + ```bash |
| 109 | + $ pip install pyflakes |
| 110 | + $ pyflakes path/to/module.py |
| 111 | + ``` |
| 112 | + |
| 113 | +- No PEP8 warnings, check with: |
| 114 | + |
| 115 | + ```bash |
| 116 | + $ pip install pep8 |
| 117 | + $ pep8 path/to/module.py |
| 118 | + ``` |
| 119 | + |
| 120 | +Filing bugs |
| 121 | +----------- |
| 122 | +We use GitHub issues to track all bugs and feature requests; feel free to |
| 123 | +open an issue if you have found a bug or wish to see a feature implemented. |
| 124 | + |
| 125 | +It is recommended to check that your issue complies with the |
| 126 | +following rules before submitting: |
| 127 | + |
| 128 | +- Verify that your issue is not being currently addressed by other |
| 129 | + [issues](https://github.com/openml/openml-python/issues) |
| 130 | + or [pull requests](https://github.com/openml/openml-python/pulls). |
| 131 | + |
| 132 | +- Please ensure all code snippets and error messages are formatted in |
| 133 | + appropriate code blocks. |
| 134 | + See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks). |
| 135 | + |
| 136 | +- Please include your operating system type and version number, as well |
| 137 | + as your Python, openml, scikit-learn, numpy, and scipy versions. This information |
| 138 | + can be found by running the following code snippet: |
| 139 | + |
| 140 | + ```python |
| 141 | + import platform; print(platform.platform()) |
| 142 | + import sys; print("Python", sys.version) |
| 143 | + import numpy; print("NumPy", numpy.__version__) |
| 144 | + import scipy; print("SciPy", scipy.__version__) |
| 145 | + import sklearn; print("Scikit-Learn", sklearn.__version__) |
| 146 | + import openml; print("OpenML", openml.__version__) |
| 147 | + ``` |
| 148 | + |
| 149 | +New contributor tips |
| 150 | +-------------------- |
| 151 | + |
| 152 | +A great way to start contributing to scikit-learn is to pick an item |
| 153 | +from the list of [Easy issues](https://github.com/openml/openml-python/issues?q=label%3Aeasy) |
| 154 | +in the issue tracker. Resolving these issues allow you to start |
| 155 | +contributing to the project without much prior knowledge. Your |
| 156 | +assistance in this area will be greatly appreciated by the more |
| 157 | +experienced developers as it helps free up their time to concentrate on |
| 158 | +other issues. |
| 159 | + |
| 160 | +Documentation |
| 161 | +------------- |
| 162 | + |
| 163 | +We are glad to accept any sort of documentation: function docstrings, |
| 164 | +reStructuredText documents (like this one), tutorials, etc. |
| 165 | +reStructuredText documents live in the source code repository under the |
| 166 | +doc/ directory. |
| 167 | + |
| 168 | +You can edit the documentation using any text editor and then generate |
| 169 | +the HTML output by typing ``make html`` from the doc/ directory. |
| 170 | +The resulting HTML files will be placed in ``build/html/`` and are viewable in |
| 171 | +a web browser. See the ``README`` file in the ``doc/`` directory for more |
| 172 | +information. |
| 173 | + |
| 174 | +For building the documentation, you will need |
| 175 | +[sphinx](http://sphinx.pocoo.org/), |
| 176 | +[matplotlib](http://matplotlib.org/), and |
| 177 | +[pillow](http://pillow.readthedocs.io/en/latest/). |
| 178 | +[sphinx-bootstrap-theme](https://ryan-roemer.github.io/sphinx-bootstrap-theme/) |
0 commit comments