Skip to content

Commit 2bfd581

Browse files
PGijsbersPGijsbers
authored
Restructure Contributing documentation (#928)
* Mention the initialization of pre-commit * Restructure the two contribution guidelines The rst file will now have general contribution information, for contributions that are related to openml-python, but not actually to the openml-python repository. Information for making a contribution to the openml-python repository is in the contributing markdown file.
1 parent 6b245bd commit 2bfd581

File tree

2 files changed

+117
-181
lines changed

2 files changed

+117
-181
lines changed

‎CONTRIBUTING.md‎

Lines changed: 100 additions & 40 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,76 @@
1-
How to contribute
2-
-----------------
1+
This document describes the workflow on how to contribute to the openml-python package.
2+
If you are interested in connecting a machine learning package with OpenML (i.e.
3+
write an openml-python extension) or want to find other ways to contribute, see [this page](https://openml.github.io/openml-python/master/contributing.html#contributing).
34

4-
The preferred workflow for contributing to the OpenML python connector is to
5+
Scope of the package
6+
--------------------
7+
8+
The scope of the OpenML Python package is to provide a Python interface to
9+
the OpenML platform which integrates well with Python's scientific stack, most
10+
notably [numpy](http://www.numpy.org/), [scipy](https://www.scipy.org/) and
11+
[pandas](https://pandas.pydata.org/).
12+
To reduce opportunity costs and demonstrate the usage of the package, it also
13+
implements an interface to the most popular machine learning package written
14+
in Python, [scikit-learn](http://scikit-learn.org/stable/index.html).
15+
Thereby it will automatically be compatible with many machine learning
16+
libraries written in Python.
17+
18+
We aim to keep the package as light-weight as possible and we will try to
19+
keep the number of potential installation dependencies as low as possible.
20+
Therefore, the connection to other machine learning libraries such as
21+
*pytorch*, *keras* or *tensorflow* should not be done directly inside this
22+
package, but in a separate package using the OpenML Python connector.
23+
More information on OpenML Python connectors can be found [here](https://openml.github.io/openml-python/master/contributing.html#contributing).
24+
25+
Reporting bugs
26+
--------------
27+
We use GitHub issues to track all bugs and feature requests; feel free to
28+
open an issue if you have found a bug or wish to see a feature implemented.
29+
30+
It is recommended to check that your issue complies with the
31+
following rules before submitting:
32+
33+
- Verify that your issue is not being currently addressed by other
34+
[issues](https://github.com/openml/openml-python/issues)
35+
or [pull requests](https://github.com/openml/openml-python/pulls).
36+
37+
- Please ensure all code snippets and error messages are formatted in
38+
appropriate code blocks.
39+
See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks).
40+
41+
- Please include your operating system type and version number, as well
42+
as your Python, openml, scikit-learn, numpy, and scipy versions. This information
43+
can be found by running the following code snippet:
44+
```python
45+
import platform; print(platform.platform())
46+
import sys; print("Python", sys.version)
47+
import numpy; print("NumPy", numpy.__version__)
48+
import scipy; print("SciPy", scipy.__version__)
49+
import sklearn; print("Scikit-Learn", sklearn.__version__)
50+
import openml; print("OpenML", openml.__version__)
51+
```
52+
53+
Determine what contribution to make
54+
-----------------------------------
55+
Great! You've decided you want to help out. Now what?
56+
All contributions should be linked to issues on the [Github issue tracker](https://github.com/openml/openml-python/issues).
57+
In particular for new contributors, the *good first issue* label should help you find
58+
issues which are suitable for beginners. Resolving these issues allow you to start
59+
contributing to the project without much prior knowledge. Your assistance in this area
60+
will be greatly appreciated by the more experienced developers as it helps free up
61+
their time to concentrate on other issues.
62+
63+
If you encountered a particular part of the documentation or code that you want to improve,
64+
but there is no related open issue yet, open one first.
65+
This is important since you can first get feedback or pointers from experienced contributors.
66+
67+
To let everyone know you are working on an issue, please leave a comment that states you will work on the issue
68+
(or, if you have the permission, *assign* yourself to the issue). This avoids double work!
69+
70+
General git workflow
71+
--------------------
72+
73+
The preferred workflow for contributing to openml-python is to
574
fork the [main repository](https://github.com/openml/openml-python) on
675
GitHub, clone, check out the branch `develop`, and develop on a new branch
776
branch. Steps:
@@ -114,6 +183,10 @@ First install openml with its test dependencies by running
114183
$ pip install -e .[test]
115184
```
116185
from the repository folder.
186+
Then configure pre-commit through
187+
```bash
188+
$ pre-commit install
189+
```
117190
This will install dependencies to run unit tests, as well as [pre-commit](https://pre-commit.com/).
118191
To run the unit tests, and check their code coverage, run:
119192
```bash
@@ -141,51 +214,38 @@ If you want to run the pre-commit tests without doing a commit, run:
141214
```
142215
Make sure to do this at least once before your first commit to check your setup works.
143216

144-
Filing bugs
145-
-----------
146-
We use GitHub issues to track all bugs and feature requests; feel free to
147-
open an issue if you have found a bug or wish to see a feature implemented.
148-
149-
It is recommended to check that your issue complies with the
150-
following rules before submitting:
151-
152-
- Verify that your issue is not being currently addressed by other
153-
[issues](https://github.com/openml/openml-python/issues)
154-
or [pull requests](https://github.com/openml/openml-python/pulls).
155-
156-
- Please ensure all code snippets and error messages are formatted in
157-
appropriate code blocks.
158-
See [Creating and highlighting code blocks](https://help.github.com/articles/creating-and-highlighting-code-blocks).
159-
160-
- Please include your operating system type and version number, as well
161-
as your Python, openml, scikit-learn, numpy, and scipy versions. This information
162-
can be found by running the following code snippet:
217+
Executing a specific unit test can be done by specifying the module, test case, and test.
218+
To obtain a hierarchical list of all tests, run
163219

164-
```python
165-
import platform; print(platform.platform())
166-
import sys; print("Python", sys.version)
167-
import numpy; print("NumPy", numpy.__version__)
168-
import scipy; print("SciPy", scipy.__version__)
169-
import sklearn; print("Scikit-Learn", sklearn.__version__)
170-
import openml; print("OpenML", openml.__version__)
171-
```
220+
```bash
221+
$ pytest --collect-only
222+
223+
<Module 'tests/test_datasets/test_dataset.py'>
224+
<UnitTestCase 'OpenMLDatasetTest'>
225+
<TestCaseFunction 'test_dataset_format_constructor'>
226+
<TestCaseFunction 'test_get_data'>
227+
<TestCaseFunction 'test_get_data_rowid_and_ignore_and_target'>
228+
<TestCaseFunction 'test_get_data_with_ignore_attributes'>
229+
<TestCaseFunction 'test_get_data_with_rowid'>
230+
<TestCaseFunction 'test_get_data_with_target'>
231+
<UnitTestCase 'OpenMLDatasetTestOnTestServer'>
232+
<TestCaseFunction 'test_tagging'>
233+
```
172234

173-
New contributor tips
174-
--------------------
235+
You may then run a specific module, test case, or unit test respectively:
236+
```bash
237+
$ pytest tests/test_datasets/test_dataset.py
238+
$ pytest tests/test_datasets/test_dataset.py::OpenMLDatasetTest
239+
$ pytest tests/test_datasets/test_dataset.py::OpenMLDatasetTest::test_get_data
240+
```
175241

176-
A great way to start contributing to openml-python is to pick an item
177-
from the list of [Good First Issues](https://github.com/openml/openml-python/labels/Good%20first%20issue)
178-
in the issue tracker. Resolving these issues allow you to start
179-
contributing to the project without much prior knowledge. Your
180-
assistance in this area will be greatly appreciated by the more
181-
experienced developers as it helps free up their time to concentrate on
182-
other issues.
242+
Happy testing!
183243

184244
Documentation
185245
-------------
186246

187247
We are glad to accept any sort of documentation: function docstrings,
188-
reStructuredText documents (like this one), tutorials, etc.
248+
reStructuredText documents, tutorials, etc.
189249
reStructuredText documents live in the source code repository under the
190250
doc/ directory.
191251

‎doc/contributing.rst‎

Lines changed: 17 additions & 141 deletions
Original file line numberDiff line numberDiff line change
@@ -2,158 +2,34 @@
22

33
.. _contributing:
44

5-
65
============
76
Contributing
87
============
98

10-
Contribution to the OpenML package is highly appreciated. Currently,
11-
there is a lot of work left on implementing API calls,
12-
testing them and providing examples to allow new users to easily use the
13-
OpenML package. See the :ref:`issues` section for open tasks.
14-
15-
Please mark yourself as contributor in a github issue if you start working on
16-
something to avoid duplicate work. If you're part of the OpenML organization
17-
you can use github's assign feature, otherwise you can just leave a comment.
18-
19-
.. _scope:
20-
21-
Scope of the package
22-
====================
23-
24-
The scope of the OpenML Python package is to provide a Python interface to
25-
the OpenML platform which integrates well with Python's scientific stack, most
26-
notably `numpy <http://www.numpy.org/>`_ and `scipy <https://www.scipy.org/>`_.
27-
To reduce opportunity costs and demonstrate the usage of the package, it also
28-
implements an interface to the most popular machine learning package written
29-
in Python, `scikit-learn <http://scikit-learn.org/stable/index.html>`_.
30-
Thereby it will automatically be compatible with many machine learning
31-
libraries written in Python.
32-
33-
We aim to keep the package as light-weight as possible and we will try to
34-
keep the number of potential installation dependencies as low as possible.
35-
Therefore, the connection to other machine learning libraries such as
36-
*pytorch*, *keras* or *tensorflow* should not be done directly inside this
37-
package, but in a separate package using the OpenML Python connector.
38-
39-
.. _issues:
40-
41-
Open issues and potential todos
42-
===============================
43-
44-
We collect open issues and feature requests in an `issue tracker on github <https://github.com/openml/openml-python/issues>`_.
45-
The issue tracker contains issues marked as *Good first issue*, which shows
46-
issues which are good for beginners. We also maintain a somewhat up-to-date
47-
`roadmap <https://github.com/openml/openml-python/issues/410>`_ which
48-
contains longer-term goals.
49-
50-
.. _how_to_contribute:
51-
52-
How to contribute
53-
=================
54-
55-
There are many ways to contribute to the development of the OpenML Python
56-
connector and OpenML in general. We welcome all kinds of contributions,
57-
especially:
58-
59-
* Source code which fixes an issue, improves usability or implements a new
60-
feature.
61-
* Improvements to the documentation, which can be found in the ``doc``
62-
directory.
63-
* New examples - current examples can be found in the ``examples`` directory.
64-
* Bug reports - if something doesn't work for you or is cumbersome, please
65-
open a new issue to let us know about the problem.
66-
* Use the package and spread the word.
67-
* `Cite OpenML <https://www.openml.org/cite>`_ if you use it in a scientific
68-
publication.
69-
* Visit one of our `hackathons <https://meet.openml.org/>`_.
70-
* Check out how to `contribute to the main OpenML project <https://github.com/openml/OpenML/blob/master/CONTRIBUTING.md>`_.
71-
72-
Contributing code
73-
~~~~~~~~~~~~~~~~~
74-
75-
Our guidelines on code contribution can be found in `this file <https://github.com/openml/openml-python/blob/master/CONTRIBUTING.md>`_.
76-
77-
.. _installation:
78-
79-
Installation
80-
============
81-
82-
Installation from github
83-
~~~~~~~~~~~~~~~~~~~~~~~~
84-
85-
The package source code is available from
86-
`github <https://github.com/openml/openml-python>`_ and can be obtained with:
87-
88-
.. code:: bash
89-
90-
git clone https://github.com/openml/openml-python.git
91-
92-
93-
Once you cloned the package, change into the new directory.
94-
If you are a regular user, install with
95-
96-
.. code:: bash
97-
98-
pip install -e .
99-
100-
If you are a contributor, you will also need to install test dependencies
101-
102-
.. code:: bash
9+
Contribution to the OpenML package is highly appreciated in all forms.
10+
In particular, a few ways to contribute to openml-python are:
10311

104-
pip install -e ".[test]"
12+
* A direct contribution to the package, by means of improving the
13+
code, documentation or examples. To get started, see `this file <https://github.com/openml/openml-python/blob/master/CONTRIBUTING.md>`_
14+
with details on how to set up your environment to develop for openml-python.
10515

16+
* A contribution to an openml-python extension. An extension package allows OpenML to interface
17+
with a machine learning package (such as scikit-learn or keras). These extensions
18+
are hosted in separate repositories and may have their own guidelines.
19+
For more information, see the :ref:`extensions` below.
10620

107-
Testing
108-
=======
109-
110-
From within the directory of the cloned package, execute:
111-
112-
.. code:: bash
113-
114-
pytest tests/
115-
116-
Executing a specific test can be done by specifying the module, test case, and test.
117-
To obtain a hierarchical list of all tests, run
118-
119-
.. code:: bash
120-
121-
pytest --collect-only
122-
123-
.. code:: bash
124-
125-
<Module 'tests/test_datasets/test_dataset.py'>
126-
<UnitTestCase 'OpenMLDatasetTest'>
127-
<TestCaseFunction 'test_dataset_format_constructor'>
128-
<TestCaseFunction 'test_get_data'>
129-
<TestCaseFunction 'test_get_data_rowid_and_ignore_and_target'>
130-
<TestCaseFunction 'test_get_data_with_ignore_attributes'>
131-
<TestCaseFunction 'test_get_data_with_rowid'>
132-
<TestCaseFunction 'test_get_data_with_target'>
133-
<UnitTestCase 'OpenMLDatasetTestOnTestServer'>
134-
<TestCaseFunction 'test_tagging'>
135-
136-
137-
To run a specific module, add the module name, for instance:
138-
139-
.. code:: bash
140-
141-
pytest tests/test_datasets/test_dataset.py
142-
143-
To run a specific unit test case, add the test case name, for instance:
144-
145-
.. code:: bash
146-
147-
pytest tests/test_datasets/test_dataset.py::OpenMLDatasetTest
148-
149-
To run a specific unit test, add the test name, for instance:
21+
* Bug reports. If something doesn't work for you or is cumbersome, please
22+
open a new issue to let us know about the problem.
23+
See `this section <https://github.com/openml/openml-python/blob/develop/CONTRIBUTING.md#reporting-bugs>`_.
15024

151-
.. code:: bash
25+
* `Cite OpenML <https://www.openml.org/cite>`_ if you use it in a scientific
26+
publication.
15227

153-
pytest tests/test_datasets/test_dataset.py::OpenMLDatasetTest::test_get_data
28+
* Visit one of our `hackathons <https://meet.openml.org/>`_.
15429

155-
Happy testing!
30+
* Contribute to another OpenML project, such as `the main OpenML project <https://github.com/openml/OpenML/blob/master/CONTRIBUTING.md>`_.
15631

32+
.. _extensions:
15733

15834
Connecting new machine learning libraries
15935
=========================================

0 commit comments

Comments
 (0)