Quickstart Guide to Contributing#

Creating a development environment#

To make and test code changes and build the documentation locally you will need to create a development environment. If you run into problems at any stage do not hesitate to TEMPLATE ask for help.

Set up GitHub and Git#

scikit-plots is hosted on GitHub, and to contribute, you will need a GitHub account.

We use Git for version control and to allow many people to work together on the project. See the GitHub quickstart instructions for installing and configuring git, as well as the git resources page.

If you are new to contributing to projects through forking on GitHub, see the GitHub documentation for contributing to projects.

Install a C compiler if needed#

How to do this will depend on your platform.

Windows

You will need Build Tools for Visual Studio.

Note

You DO NOT need to install Visual Studio. You only need “Build Tools for Visual Studio” found by scrolling down to “All downloads” -> “Tools for Visual Studio” -> “Build Tools for Visual Studio”.

Alternative options include:

Install the necessary components on the command line using vs_BuildTools.exe.
Use the WSL.

MacOS

Install the Developer Tools using xcode-select --install. There is no need to install the full Xcode application and this command will install only the command line tools and developer utilities.

Further details and related information can be found at https://devguide.python.org/setup/#macos.

Linux

For Linux-based installations, you won’t have to install any additional components.

Create a clone of scikit-plots#

If you have not done so already, you will need your own copy of scikit-plots to build it and/or contribute to the source. scikit-plots is hosted in the scikit-plots GitHub repository and you need to make a clone.

First, create a GitHub Fork by going to the scikit-plots project page and hitting the Fork button.

Next, clone your GitHub fork to your machine:

git clone https://github.com/YOUR-USER-NAME/scikit-plots.git
git submodule update --init  # download submodules
cd scikit-plots
git remote add upstream https://github.com/scikit-plots/scikit-plots.git
git fetch upstream --tags

This creates the directory scikit-plots and connects your repository to the upstream (main project) scikit-plots repository.

You can see the remote repositories as follows:

>>> git remote --verbose

You will see something like:

>>> origin  git@github.com:YOUR-USER-NAME/scikit-plots.git (fetch)
>>> origin  git@github.com:YOUR-USER-NAME/scikit-plots.git (push)
>>> upstream        https://github.com/scikit-plots/scikit-plots.git (fetch)
>>> upstream        https://github.com/scikit-plots/scikit-plots.git (push)

Create an isolated development environment#

A key requirement is to have an isolated Python environment, meaning that it is isolated from both your system Python and any other Python environments you may have for doing other work. This is important because the development environment will often be unstable and possibly broken at times, and you don’t want to break your other work.

There are many good options for doing this, including a number of virtual environment managers (e.g., the Python standard library venv module). Users who have a preference for a particular virtual environment manager are encouraged to use it!

For this quickstart guide we use the conda package manager provided by miniforge. This is a popular choice and generally works well, especially for newcomers. It is easy to install and use on all platforms and it makes it easy to install different Python versions which can be useful for testing.

Install miniforge and conda#

If you do not already have conda installed, download and install miniforge. The details depend on your system but the end result is to provide a conda executable that you can use to create and manage isolated Python environments.

Now create and activate an skplt-dev conda environment using the following:

>>> conda create -n skplt-dev python graphviz
>>> conda activate skplt-dev

Note the graphviz package is required for building the documentation.

Install the development version of scikit-plots#

Now you can install the development version of scikit-plots into your new environment. This will install the latest version of scikit-plots from your local git repo, along with all the dependencies needed to build and fully test scikit-plots:

>>> python -m pip install --no-build-isolation --no-cache-dir -e .[dev,build,test,docs] -v

Checking the build

At this point you should be able to import scikitplot from your locally built version:

>>> python -c 'import scikitplot; scikitplot.show_config()'

Next you may want to try running some or all of the scikitplot unit tests. Running the full test suite can take a few minutes, so you may want to start with a single sub-package (e.g. KeyToDataScience):

>>> # run a sub set of the test suite
>>> pytest scikitplot/kds

>>> # or the whole suite
>>> pytest

Details on running and writing tests can be found in the Testing guidelines section.

Install pre-commit#

This is optional, but highly recommended. Pre-commit is a tool that runs a number of Continuous Integration (CI) checks (e.g. code formatting) on your code before you commit it. If you skip this step then it is likely that one or more of those CI checks will fail when you make a pull request, resulting in lost time (yours and CI resources).

Installation is straightforward. From the root of the scikit-plots repository, run:

>>> pre-commit install

Now all of the styling checks will be run each time you commit changes, ensuring that the CI formatting checks for your pull request will pass.

Tip

To learn more about pre-commit, see the pre-commit section.

Creating and submitting a pull request#

You can contribute bug fixes, new features, and documentation updates by submitting a GitHub pull request (PR). This section will guide you through the process. We encourage you to ask for help if you get stuck. The scikit-plots community is welcoming and friendly and will help you!

If you are new to the scikit-plots Project and interested to submit a large patch (e.g., a new big feature or significant refactoring), we encourage you to first discuss your ideas on GitHub to increase the chance of your PR being accepted.

Creating a branch#

Your local main branch should always reflect the current state of scikit-plots repository. First ensure it’s up-to-date with the main scikit-plots repository:

>>> git switch main
>>> git pull upstream main --ff-only

Now create a development branch for making your changes. For example:

>>> git switch -c subpackage-bug-fix

This changes your working branch from main to the subpackage-bug-fix branch. Keep any changes in this branch specific to one bug or feature so it is clear what the branch brings to scikit-plots. You can have many feature branches and switch in between them using the git switch command.

Using a descriptive branch name can help you stay organized. For example `kds-commented-header` might be a good name for a branch that fixes the commented header issue #15513 in the kds sub-package.

When you want to update the feature branch with changes in main after you created the branch, check the section on updating a PR.

Making code or documentation changes#

Now comes the fun part where you use your favorite editor or IDE to make changes to the code or documentation! At a high level this breaks into a few parts:

Make changes: Make the changes you want to make. This could be fixing a bug, adding a new feature, or updating the documentation.
Test changes: For code changes, ensure that they work as expected following the process outlined in the Testing guidelines section.
Build documentation: If you are updating the documentation, you will want to build the documentation to ensure that it looks good.
Add a changelog entry: For most code changes you will need to add-changelog.

Tip

For more information and examples see The editing workflow section.

You can see a summary of the changes you’ve currently made by running:

git status

You can then commit your all your changes to your local repository with an explanatory commit message:

git add files-that-you-changed ...
git commit -m "your commit message goes here"

Important

Never merge changes from upstream/main into your feature branch. If changes in main require changes to our code you must rebase.

Pushing your changes#

When you want your changes to appear publicly on your GitHub page, push your forked feature branch’s commits:

>>> git push origin --set-upstream subpackage-bug-fix

Here origin is the default name given to your fork on GitHub.

Now your code is on GitHub, but it is not visible to the scikit-plots maintainers. For that to happen, a pull request needs to be submitted on GitHub.

The first time you push to a new branch on GitHub, you will see a message like below with a useful link to create a pull request:

>>> remote: Create a pull request for 'subpackage-bug-fix' on GitHub by visiting:
>>> remote:      https://github.com/YOUR-USER-NAME/scikit-plots/pull/new/subpackage-bug-fix

Making a pull request#

If everything looks good, you are ready to make a pull request (PR). A PR is how code from your local repository becomes available to the GitHub community to review and merged into project to appear the in the next release.

Most of the time you can just follow the link that git provided when you pushed your branch and create the PR. If you don’t have that link (and for a few more details), you can follow the pull-request instructions.

Follow the instructions in the PR template and fill it out as completely as possible.

If your PR is still a work in progress then instead of clicking “Create pull request”, click on the small down arrow next to it and select “Create draft pull request”. In addition, if your commits are not ready for CI testing, you should include [ci skip] the last commit message – but note that code formatting checks and documentation building will still be done. Formatting and style errors should already have been fixed before committing if you have locally installed pre-commit; but if you have not, you can use the pre-commit_bot to fix them automatically in the PR.

Once submitted (and marked as ready), this request goes to the scikit-plots maintainers and they will review the PR.

Updating your pull request#

Based on the review you get on your pull request, you will probably need to make some adjustments. You can follow the code committing steps again to address any feedback and update your pull request:

>>> git push origin subpackage-bug-fix

Any git push will automatically update your pull request with your branch’s changes and restart the Continuous Integration checks.