Contributing#

Thank you for your interest in contributing to skore! We welcome contributions from everyone and appreciate you taking the time to get involved.

This project is hosted on probabl-ai/skore.

Below are some guidelines to help you get started.

Preamble#

Our values#

We aspire to treat everybody equally, and value their contributions. We are particularly seeking people from underrepresented backgrounds in Open Source Software to participate and contribute their expertise and experience.

Decisions are made based on technical merit, consensus, and roadmap priorities.

Code is not the only way to help the project. Reviewing pull requests, answering questions to help others on mailing lists or issues, organizing and teaching tutorials, working on the website, improving the documentation, are all priceless contributions.

We abide by the principles of openness, respect, and consideration of others of the Python Software Foundation: https://www.python.org/psf/codeofconduct/

Automated contributions policy#

Please refrain from submitting issues or pull requests generated by fully-automated tools. Maintainers reserve the right, at their sole discretion, to close such submissions and to block any account responsible for them.

Ideally, contributions should follow from a human-to-human discussion in the form of an issue.

Signing commits#

You have to sign your commits before submitting a pull request. For a pull request to be accepted, all the commits inside of it must be signed.

GitHub supports commit signing using GPG, SSH, or S/MIME. Signed commits are marked as “Verified” on GitHub, providing confidence in the origin of your changes. For setup instructions and more details, please refer to GitHub’s guide on signing commits.

Questions, bugs, and feature requests#

If you have any questions, feel free to reach out:

Join our community on Discord for general chat and Q&A.
Alternatively, you can start a discussion on GitHub.
Both bugs and feature requests can be filed in the GitHub issue tracker:

When filing an issue:

Check if your issue does not already exist.
For new issues, we recommend some templates but feel free to open a blank issue.
Use short, self-contained, correct examples to help us understand your issue.

Development#

Quick start#

You’ll need python >=3.9, <3.13.

Setting up your development environment#

Fork the repository on GitHub, then clone your fork locally, and add a git remote to the main skore repository. You will find below some code you can use in your terminal, using HTTPS connection as an example.

# Clone your fork of the repo
git clone https://github.com/YOUR_USERNAME/skore.git

# Navigate to the newly cloned directory
cd skore

# Add the original repository as a remote
git remote add upstream https://github.com/probabl-ai/skore.git

# Create a new branch for your issue
git checkout -b issue-NAME_OF_ISSUE

We strongly recommend using a virtual environment to isolate your development dependencies.

Once your environment is set up, install the development dependencies and setup pre-commit with:

make install-skore
On old CPU architecture to get the support of polars:
make install-skore-lts-cpu

Choosing an issue#

If you are new to open-source, you can start by an issue tagged “good first issue”.

The implementation of some issues are not very detailed. You can either propose a solution, or choose only the issues with a “Ready” status.

Pull requests#

Quick start:

Create a branch for your changes.
Commit your changes.
Push to your fork.
Submit a pull request to the main branch.
- Link your PR to its corresponding issue (if any).
- You can mark your PR as draft if it is not ready to be reviewed by maintainers. You can use draft PR to get help on the code if needed.

We use the conventional commits format, and we automatically check that the PR title fits this format:

In particular, commits are “sentence case”, meaning that the fix: Fix issue title passes, while fix: fix issue does not.
Generally, the description of a commit should start with a verb in the imperative voice, so that it would properly complete the sentence: When applied, this commit will [...].
Examples of correct PR titles: docs: Update the docstrings or feat: Remove CrossValidationAggregationItem.

Skore is a company-driven project. We might provide extensive help to bring PRs to be merged to meet internal deadlines. In such cases, we will warn you in the PR.

Tests#

When adding a new feature to skore, please make sure to:

Include unit tests

Add tests to verify that your feature has as few bugs as possible. Tests are in the tests/ directory.
Verify existing examples

Check if your newly introduced changes do not impact existing examples.

You can run all examples with:
```
cd sphinx && make html
```
Alternatively, you can run individual examples with:
```
python <example_file>
```
Update or add examples if needed
- For a minor feature, adjust one existing example to demonstrate your change. Avoid creating many short example files.
- For a major feature, add a single, concise example under examples/ (or update the gallery) that highlights the new capability.

To run the tests locally, you may run:

make test

Linting#

We use the linter ruff to make sure that the code is formatted correctly:

make lint

Pre-commit Hooks#

We use pre-commit hooks to ensure code quality before changes are committed. These hooks were installed during setup, but you can manually run them with:

pre-commit run --all-files

Documentation#

Setup#

Our documentation uses the PyData Sphinx Theme.

To build the docs:

cd sphinx
make html

You can access the local build at:

open build/html/index.html

A bot will automatically comment on your PR with a link to a documentation preview. Use this link to verify that your changes render correctly.

Skipping examples when building the docs#

The examples can take a long time to build, so if you are not working on them you can instead run the following to avoid building them altogether:

make html-noplot

If you are working on an example and wish to only build that one, you can do so by temporarily editing sphinx/conf.py. Follow the sphinx-gallery documentation for more information. By default, the examples that are built are Python files that start with plot_.

Note that by default, if an example has not changed since the last time you built it, it will not be re-built.

Contributing to the docstrings#

When writing documentation, whether it be online, docstrings or help messages in the CLI and in the UI, we strive to follow some conventions that are listed below. These might be updated as time goes on.

The docstring will be compiled using Sphinx numpydoc so use RST (ReStructured Text) for bold, URLs, etc.
Argument descriptions should be written so that the following sentence makes sense: Argument <argument> designates <argument description>
Argument descriptions start with lower case, and do not end with a period or other punctuation
Argument descriptions start with “the” where relevant, and “whether” for booleans
Text is written in US English (use “visualize” rather than “visualise”)
In the CLI, positional arguments are written in snake case (snake_case), keyword arguments in kebab case (kebab-case)
When there is a default argument, it should be shown in the help message, typically with (default: <default value>) at the end of the message
Use clear, concise language (e.g. that can be understood by non-native English speakers)

Contributing to the examples#

The examples are stored in the examples folder:

They are organized in subcategories.
They should be written in a python script (.py), with cells marked by # %%, to separate code cells and markdown cells, as they will be rendered as notebooks (.ipynb).
The file should start with a docstring giving the example title.
No example should require to have large files stored in this repository. For example, no dataset should be stored, it should be downloaded in the script.
When built (using make html for example), these examples will automatically be converted into RST files in the sphinx/auto_examples subfolder. This subfolder is listed in the gitignore and cannot be pushed.
If you are visualizing the examples on the online documentation and notice some typos or things that could be improved, make sure that you are viewing the dev version of the documentation which is the latest version (e.g. check that the typo has not already been solved for example).
New examples should use datasets that are sufficiently interesting yet reasonably sized (avoid synthetic datasets with near-perfect scores). As examples are executed during the documentation build, their runtime must remain short (ideally under a few minutes).

Guidelines for creating effective examples:

Types of examples: - Doctests: Use these in API documentation for demonstrating simple usage patterns. - User guide examples: Create comprehensive examples that demonstrate functionality in real-world contexts.
Small features: For minor features, for instance when extending existing assets or easying a supported use-case, don’t create standalone examples. Instead, incorporate these into existing relevant documentation where they make sense contextually.
Example content: Focus on demonstrating the core concept rather than exhaustively listing all possible arguments. Show the global idea of how to use the feature effectively.
Dataset selection: - Use meaningful, realistic datasets (not synthetic data with artificially high scores) - Ensure examples execute efficiently (under a few minutes) - Prefer built-in or easily downloadable datasets - If downloading data, include clear code for this process

Contributing to the README#

The README.md file can be modified and is part of the documentation (although it is not included in the online documentation). This file is used to be presented on PyPI.

Signing Commits#

You must sign your commits before submitting a pull request. For a pull request to be accepted, all the commits inside of it must be signed.

To sign your commits:

git commit -S -m "Your commit message"

If you haven’t set up commit signing yet, GitHub supports signing using GPG, SSH, or S/MIME. Signed commits are marked as “Verified” on GitHub, providing confidence in the origin of your changes. For setup instructions and more details, please refer to GitHub’s guide on signing commits.

Pull Request Checklist#

Before marking your pull request as ready for review, ensure you have:

Created or updated unit tests for your changes
Run all tests locally and verified they pass
Updated documentation if necessary
Make sure the documentation can be ran without warning nor failure.
Run pre-commit hooks on your code
Signed all your commits

This checklist helps maintain code quality and ensures a smooth review process.