How to contribute¶

Welcome to sktime’s contributing guide!

sktime is a community-driven project and your help is extremely welcome.

How to get started
Reporting bugs
Where to contribute
Installation
Git and GitHub workflow
Continuous integration
API design
Documentation
Dependencies
Coding style
Infrastructure
Releases
Acknowledging contributions

How to get started ¶

We are particularly motivated to support new contributors and people who are looking to learn and develop their skills.

Good-first issues. Check out our good-first issues. If you are interested in one of them, simply comment on the issue!
Mentoring. New to sktime? Apply to sktime’s own mentoring program!
The Turing Way. Check out their Guide for Reproducible Research to get started and learn more about open-source collaboration.

Note

If you get stuck, chat with us on Gitter or Discord.

Reporting 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.

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

Verify that your issue is not being currently addressed by other issues or pull requests.
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.

Note

To find out more about how to take part in sktime’s community, check out our governance guidelines.

Where to contribute ¶

We value all kinds of contributions – not just code. For a detailed overview of current and future work, check out our Roadmap.

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 protected]:<username>/sktime.git
cd sktime
```
where <username> is your GitHub username.

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>/sktime.git (fetch)
> origin    https://github.com/<username>/sktime.git (push)
> upstream  https://github.com/alan-turing-institute/sktime.git (fetch)
> upstream  https://github.com/alan-turing-institute/sktime.git (push)

Sync the main branch of your fork with the upstream repository:

 git fetch upstream
git checkout main
git merge upstream/main

Create a new feature branch from the main branch to hold your changes:
```
 git checkout main
git checkout -b <feature-branch>
```
Always use a feature branch. It’s good practice to never work on the main branch! Name the feature branch after your contribution.
Develop your contribution on your feature branch. Add changed files using git add and then git commit files 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, open a draft pull request.

Note

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.

Note

If any of the above seems like magic to you, look up the Git documentation. If you get stuck, chat with us on Gitter or Discord.

Continuous integration ¶

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 ¶

We use pre-commit for code quality checks. These checks run automatically before you make a new commit.

To set up pre-commit, follow these steps:

Install pre-commit:

 pip install pre-commit

Set up pre-commit:

 pre-commit install

Once installed, pre-commit will automatically run our code quality checks on the files you changed whenever you make a new commit.

You can find our pre-commit configuration in .pre-commit-config.yaml. Additional configurations can be found in setup.cfg.

Note

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.

Unit testing ¶

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 of sktime which will include the changes you make.

Note

For trouble shooting on different operating systems, please see our detailed installation instructions.

To run all unit tests, run:
```
 pytest sktime/
```

Test coverage ¶

We use coverage, the pytest-cov plugin, and codecov for test coverage.

API design ¶

The general design approach of sktime is described in the paper “Designing Machine Learning Toolboxes: Concepts, Principles and Patterns”.

Note

This is a first draft of the paper. Feedback and improvement suggestions are very welcome!

Documentation ¶

We use sphinx to build our documentation and readthedocs to host it. You can find our latest documentation here.

The source files can be found in docs/source/. 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 index.rst file.

To build the documentation locally, you need to install a few extra dependencies listed in docs/requirements.txt.

To install extra requirements from the root directory, run:
```
 pip install -r docs/requirements.txt
```
To build the website locally, run:
```
 make docs
```

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.

Dependencies ¶

We try to keep the number of core dependencies to a minimum and rely on other packages as soft dependencies when feasible.

Note

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 raise a user-friendly error message. This is handled through our _check_soft_dependencies defined here.

We use contiunous integration tests to check if all soft dependencies are properly isolated to specific modules. If you add a new soft dependency, make sure to add it here together with the module that depends on it.

Coding style ¶

We follow the PEP8 coding guidelines. A good example can be found here.

We use the pre-commit workflow together with black and flake8 to automatically apply consistent formatting and check whether your contribution complies with the PEP8 style.

For docstrings, we use the numpy docstring standard, along with sktime specific conventions described in our Developer Guide’s documentation section.

In addition, we add the following guidelines:

Please check out our Glossary of Common Terms.
Use underscores to separate words in non-class names: n_instances rather than ninstances.
Avoid multiple statements on one line. Prefer a line return after a control flow statement (if/for).
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.

Infrastructure ¶

This section gives an overview of the infrastructure and continuous integration services we use.

Platform	Operation	Configuration
`Appveyor <https://ci. appveyor.com/ project/mloni ng/sktime>`__	Build/t est/distribute on Windows	.appveyor.yml
Azure Pipelines	Build/t est/distribute on Linux (manylin ux)	azure-pipelines.yml
GitHub Act ions	Build/t est/distribute on MacOS; Code quality checks	.github/workflows/
Read the Docs	Build/deploy documentation	.readthed ocs.yml
Codec ov	Test coverage	.codecov.yml, .coveragerc

Additional scripts used for building, unit testing and distribution can be found in build_tools/.

Releases ¶

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.

Note

For more details, see the Python guide for packaging and the Cython guide on compilation/distribution.

We use continuous integration services to automate the building of wheels on different platforms. The release process is triggered by pushing a non-annotated tagged commit using semantic versioning. Pushing a new tag will build the wheels for different platforms and upload them to PyPI.

You can see all available wheels here.

To make the release process easier, we have an interactive script that you can follow. Simply run:

 make release

This calls build_tools/make_release.py and will guide you through the release process.

Acknowledging contributions ¶

We follow the all-contributors specification and recognize various types of contributions. Take a look at our past and current contributors!

If you are a new contributor, make sure we add you to our list of contributors. All contributions are recorded in .all-contributorsrc.

Note

If we have missed anything, please raise an issue or chat with us on Gitter or Discord.