How to Contribute¶
Welcome to our contributing guidelines!
To find out more about how to take part in sktime’s community, check out our governance document.
How to get started¶
We are particularly motivated to support new and/or anxious contributors and people who are looking to learn and develop their skills.
The Turing Way. A great handbook and community for open science to find lots of useful resources. Check out their Guide for Reproducible Research to get started and learn more about open-source collaboration.
GitHub’s Open Source Guides. Take a look at their How to Contribute Guide to find out more about what it means to contribute.
scikit-learn’s developer guide. sktime follows scikit-learn‘s API whenever possible. We assume basic familiarity with scikit-learn. If you’re new to scikit-learn, take a look at their getting-started guide. If you’re already familiar with scikit-learn, you may still learn something new from their developers’ guide.
Mentorship programme. We have also launched sktime’s own mentorship programme. You can find out more and apply on our website!
Where to contribute¶
Areas of contribution¶
We value all kinds of contributions - not just code. The following table gives an overview of key contribution areas.
Improve or add docstrings, glossary terms, the user guide, and the example notebooks
Report bugs, improve or add unit tests, conduct field testing on real-world data sets
Improve or add functionality, fix bugs
Onboarding and mentoring of new contributors
Organize talks, tutorials or workshops, write blog posts
Improve development operations (continuous integration pipeline, GitHub bots), manage and review issues/pull requests
Design interfaces for estimators and other functionality
Finding funding, organising meetings, initiating new collaborations
For a more detailed overview of current and future work, check out our development roadmap.
If you are a new contributor, please make sure we add you to our list of contributors. All contributions are recorded in .all-contributorsrc.
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:
Please ensure all code snippets and error messages are formatted in appropriate code blocks. See Creating and highlighting code blocks.
Please be specific about what estimators and/or functions are involved and the shape of the data, as appropriate; please include a reproducible code snippet or link to a gist. If an exception is raised, please provide the traceback.
Please visit our detailed installation instructions to resolve any package issues and dependency errors before they occur in the following steps. OS specific instruction is available at the prior link.
Git and GitHub workflow¶
The preferred workflow for contributing to sktime’s repository is to fork the main repository on GitHub, clone, and develop on a new branch.
Fork the project repository 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.
Clone your fork of the sktime repo from your GitHub account to your local disk:
git clone email@example.com:USERNAME/sktime.git cd sktime
Configure and link the remote for your fork to the upstream repository:
git remote -v git remote add upstream https://github.com/alan-turing-institute/sktime.git
Verify the new upstream repository you've specified for your fork:
git remote -v > origin https://github.com/USERNAME/YOUR_FORK.git (fetch) > origin https://github.com/YOUR_USERNAME/YOUR_FORK.git (push) > upstream https://github.com/alan-turing-institute/sktime.git (fetch) > upstream https://github.com/alan-turing-institute/sktime.git (push)
mainbranch of your fork with the upstream repository:
git fetch upstream git checkout main --track origin/main git merge upstream/main
Create a new
featurebranch from the
mainbranch to hold your changes:
git checkout main git checkout -b <my-feature-branch>
Always use a
featurebranch. It's good practice to never work on the
mainbranch! Name the
featurebranch after your contribution.
Develop your contribution on your feature branch. Add changed files using
git addand then
git commitfiles to record your changes in Git:
git add <modified_files> git commit
When finished, push the changes to your GitHub account with:
git push --set-upstream origin my-feature-branch
Follow these instructions to create a pull request from your fork. If your work is still work in progress, you can open a draft pull request. We recommend to open a pull request early, so that other contributors become aware of your work and can give you feedback early on.
To add more changes, simply repeat steps 7 - 8. Pull requests are updated automatically if you push new changes to the same branch.
We use continuous integration services on GitHub to automatically check if new pull requests do not break anything and meet code quality standards such as a common coding style.
Code quality checks¶
To check if your code meets our code quality standards, you can automatically run these checks before you make a new commit using the pre-commit workflow:
pip install pre-commit
Set up pre-commit:
Once installed, pre-commit will automatically run our code quality checks on the files you changed whenenver you make a new commit.
If you want to exclude some line of code from being checked, you can add a
# noqa (no quality assurance) comment at the end of that line.
We use pytest for unit testing. To check if your code passes all tests locally, you need to install the development version of sktime and all extra dependencies.
Install all extra requirements from the root directory of sktime:
pip install -r build_tools/requirements.txt
Install the development version of sktime:
pip install -e . This installs an editable `development version <https://pip.pypa.io/en/stable/reference/pip_install/#editable-installs>`_ of sktime which will include the changes you make. For trouble shooting on different operating systems, please see our detailed `installation instructions <https://www.sktime.org/en/latest/installation.html>`_.
To run all unit tests, run:
### Test coverage
The general design approach we follow in sktime is described in the paper “Designing Machine Learning Toolboxes: Concepts, Principles and Patterns”. This is a first draft of the paper, feedback and improvement suggestions are very welcome!
The source files used to generate the online documentation can be found in docs/source/. For example, the main configuration file for sphinx is conf.py and the main page is index.rst. To add new pages, you need to add a new
.rst file and include it in the
To build the documentation locally, you need to install a few extra dependencies listed in docs/requirements.txt.
Install extra requirements from the root directory, run:
pip install -r docs/requirements.txt
To build the website locally, run:
You can find the generated files in the
sktime/docs/_build/ folder. To view the website, open
sktime/docs/_build/html/index.html with your preferred web browser.
We try to keep the number of core dependencies to a minimum and rely on other packages as soft dependencies when feasible.
A soft dependency is a dependency that is only required to import certain modules, but not necessary to use most functionality. A soft dependency is not installed automatically when the package is installed. Instead, users need to install it manually if they want to use a module that requires a soft dependency.
If you add a new dependency or change the version of an existing one, you need to update the following files:
sktime/setup.py for package installation and minimum version requirements,
build_tools/requirements.txt for continuous integration and distribution,
docs/requirements.txt for building the documentation,
.binder/requirements.txt for launching notebooks on Binder.
If a user is missing a soft dependency, we want to raise a more user-friendly error message than just a
ModuleNotFound exception. This is handled through our
_check_soft_dependencies defined here.
We also use contiunous integration tests to check if all soft dependencies are properly isolated to specific modules. So, if you add a soft dependency, please make sure to add it here together with the module that depends on it.
For docstrings, we use the numpy docstring standard.
In addition, we add the following guidelines:
Please check out our glossary of terms.
Use underscores to separate words in non-class names:
Avoid multiple statements on one line. Prefer a line return after a control flow statement (
Use absolute imports for references inside sktime.
Please don’t use
import *in the source code. It is considered harmful by the official Python recommendations. It makes the code harder to read as the origin of symbols is no longer explicitly referenced, but most important, it prevents using a static analysis tool like pyflakes to automatically find bugs.
This section gives an overview of the infrastructure and continuous integration services we use.
Build/test/distribute on Windows
Build/test/distribute on Linux (manylinux)
Build/test/distribute on MacOS; Code quality checks
Additional scripts used for building, unit testing and distribution can be found in build_tools/.
This section is for core developers. To make a new release, you need push-to-write access on our main branch.
sktime is not a pure Python package and depends on some non-Python code including Cython and C. We distribute compiled files, called wheels, for different operating systems and Python versions. More details can be found here:
We use continuous integration services to automatically build and distribute wheels across platforms and version. The release process is triggered on our continuous integration services by pushing a tagged commit using semantic versioning. Pushing a new tag will trigger a new build on the continuous integration services which will provide the wheels for different platforms and automatically upload them to PyPI. You can see all uploaded wheels here.
To make the release process easier, we have an interactive script that you can follow. Simply run:
This calls build_tools/make_release.py and will guide you through the release process.