Skip to content

Files

209 lines (126 loc) · 7.11 KB

CONTRIBUTING.rst

File metadata and controls

209 lines (126 loc) · 7.11 KB

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 https://github.com/probabl-ai/skore.

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/

Below are some guidelines to help you get started.

Questions, bugs and feature requests

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

Both bugs and feature requests can be filed in the Github issue tracker:

Development

Quick start

You'll need python >=3.9, <3.13 to build the backend and Node>=20 to build the skore-ui. Then, you can install dependencies and run the UI with:

make install-skore
make build-skore-ui
skore create
make serve-skore-ui

You are now all setup to run the library locally. If you want to contribute, please continue with the three other sections.

Backend

Install backend dependencies with:

make install-skore

You can run the API server with:

make serve-skore-ui

skore-ui

Install skore-ui dependencies with:

npm install

in the skore-ui directory.

Run the skore-ui in dev mode (for hot-reloading) with

npm run dev

in the skore-ui directory.

Then, to use the skore-ui

make build-skore-ui
make serve-skore-ui

Do not forget to do a hard refresh when changing the front-end (meta+shift+R) if the expected changes do not appear.

Pull request format

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

Tests

To run the tests locally, you may run

make test

To run only back-end tests, use:

make test-backend

To run only front-end tests, use:

make test-frontend

Linting

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

make lint

Documentation

Setup

Our documentation uses PyData Sphinx Theme.

To build the docs:

cd sphinx
make html

Then, you can access the local build via:

open build/html/index.html

The PR will also build the documentation and a bot will automatically add a comment with a link to the documentation preview to easily check the results.

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 make html-noplot to avoid building them altogether.

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.

  1. The docstring will be compiled using Sphinx numpydoc so use RST (ReStructured Text) for bold, URLs, etc.
  2. Argument descriptions should be written so that the following sentence makes sense: Argument <argument> designates <argument description>
  3. Argument descriptions start with lower case, and do not end with a period or other punctuation
  4. Argument descriptions start with "the" where relevant, and "whether" for booleans
  5. Text is written in US english ("visualize" rather than "visualise")
  6. In the CLI, positional arguments are written in snake case (snake_case), keyword arguments in kebab case (kebab-case)
  7. 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

Contributing to the examples

The examples are stored in the examples folder:

  • They are classified 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.

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.