-
Notifications
You must be signed in to change notification settings - Fork 65
Contributing guide
Want to contribute to scikit-network?
Thank you very much! Every little bit of help is greatly appreciated!
The most straightforward way is to make a pull request, be it for fixing a bug or introducing a new feature.
To ensure that the code you wrote fits nicely within the package, here are a few guidelines that you must follow.
scikit-network is divided into submodules that gather tools for a given task (e.g. clustering, ranking, ...). If you are implementing a new feature, make sure you put your code in the right submodule. If you want to implement a task which you think calls for a new submodule, create the submodule you think is appropriate and we will discuss it upon submitting the pull request.
If you are implementing tests, please note that the /tests folder is not the place where you should put them. Tests are found directly in the submodule they refer to. For instance, tests for sknetwork.linalg are located in /sknetwork/linalg/tests.
scikit-network (mostly) uses a scikit-learn-like API. That is, algorithms are objects offering a fit method for the data. Look at classes such as sknetwork.ranking.Katz if you are unsure how to proceed. Note that the base mixins (e.g. BaseRanking) make it possible to derive the fit_transform method from a valid object so you do not have to implement it yourself (it thus also makes it possible to somewhat validate your API).
As a general rule of thumb, all objects in a given submodule must offer the same API.
Your code should be easy to read for other contributors and easy to use for the end users.
To ensure the former, follow PEP8 guidelines and use type hints whenever possible (especially in function signatures). For more information, have a look at the typing package.
To ensure the latter, make sure your documentation is clear. It should follow NumPy docstring guidelines and be referenced in the relevant .rst files under the /docs/reference folder. Whenever possible, add an example in the docstring (see sknetwork.ranking.Katz for an example). Note that such examples are run as doctests and must thus be valid.
Additionally, you may produce a tutorial in the form of a JuPyter notebook. After you have checked that your tutorial format is consistent with other tutorials (see /docs/tutorial/katz.ipynb for instance), you may add it to the relevant folder under /docs/tutorial depending on the submodule you are working on.
Look at the Wiki's "Producing documentation" section for more information.
Some common objects should be denoted by the same name across the whole package for consistency, see the dedicated Wiki page.
Any code must be accompanied by relevant tests (relevance being mostly asserted by the coverage metric).
Look at the Wiki's Designing tests section for more information.
In order to check the coverage of your branch, you can either:
-
make a pull request and wait for GitHub Actions and Codecov to process your commit (can be quite long). Then, if your code passed the tests, Codecov should comment in your pull request.
-
run
py.test --cov --doctest-modules sknetwork/in your terminal.
The package has only two dependencies as long as it is pip-installed:
Compiling from source requires Cython and a compiler.
Thus, these three packages, along with the standard Python library, are the only external packages that should be used inside your code.
However, in the tutorials, you might use any of the packages listed in requirements_dev.txt. If you feel you need other packages in the tutorials, please make it clear in your pull request.
Apart from the previously mentioned packages, it is encouraged to reuse functions already implemented in scikit-network.
N.B.: Except when writing tests, any import of scikit-network functions should be done at the file level rather than the module level (e.g. write from sknetwork.linalg.normalization import normalize instead of from sknetwork.linalg import normalize). Most circular import errors stem from such mistakes.
If you have issues or interrogations, search through the Wiki as we gather some tips for specific development issues there. If your problems persist, raise an issue.