Getting Ready to Contribute

Introduction

Thank you for considering contributing to PlasmaPy — we really appreciate it! This page goes through the steps that first-time contributors can take to get set up to contribute to PlasmaPy. After taking these steps, you’ll be ready to go through the code contribution workflow.

If you run into any problems, please feel free to reach out to us in our Matrix chat room or during our weekly office hours.

Pre-requisites

Opening a terminal

The commands in this page are intended to be run in a Unix terminal. If you are new to Unix, check out this Unix tutorial and these frequently used Unix commands.

These tabs describe how to open and use a terminal on different operating systems.

There are several options for terminals on Windows.

Powershell comes pre-installed with Windows. These instructions cover opening Powershell. We recommend Powershell for a quick start, if Windows is the only operating system you use, or if you have not used Unix before.
We recommend Windows Subsystem for Linux (WSL) if you are familiar with Unix, you use macOS or Linux too, or you expect to contribute to PlasmaPy extensively. These instructions cover installing WSL. If you choose WSL, follow the tabs for Linux/WSL below.

Installing Python

Note

PlasmaPy requires a version of Python between 3.9 and 3.11. We recommend using Python 3.11.

We suggest using Anaconda to install Python. Anaconda is a versatile package and environment management system which is widely used in the data science and scientific Python communities. Anaconda includes Anaconda Navigator as its graphical user interface (GUI) and Conda as its command line interface (CLI).

If you prefer a GUI, follow these instructions on installing Anaconda Navigator.
If you prefer a CLI, follow these instructions on installing Conda.

Note

There are many other equally good ways to install Python. Python’s website describes how to download Python. Real Python has instructions on installing Python for several different operating systems (if working within WSL, follow the Linux instructions).

Using git and GitHub

Code contributions to PlasmaPy are made using git and GitHub. Before contributing code to PlasmaPy, please take the following steps:

Sign up on GitHub for a free account.
Verify that git is installed by opening a terminal and running:
```
git --version
```
If there is an error, follow these instructions to install git.
Optionally, configure git with your name with a command like:
```
git config --global user.name "Your Name"
```
You can also configure git with your email with a command like:
```
git config --global user.email "your.email@example.com"
```
You may also set your default editor with a command like the following, where notepad can be replaced with the name or path of your preferred editor:
```
git config --global core.editor notepad
```
For different editor and configuration options, check out git commands for setup and config.
Add a new SSH key to your GitHub account. This step is needed for authentication purposes.

Initial setup

Log in to GitHub.
Go to PlasmaPy’s GitHub repository.
Create a fork of PlasmaPy by clicking on Fork, followed by Create fork.
Open a terminal. Then create and/or navigate to the folder in which you want to download PlasmaPy. For example, to put PlasmaPy into a new directory called repos/ in your home directory (denoted by ~), run:
```
mkdir ~/repos
cd ~/repos
```
Clone the PlasmaPy repository with the following command, replacing YOUR-USERNAME with your GitHub username. This will create a subdirectory called PlasmaPy/ containing your local clone of the repository.
```
git clone git@github.com:YOUR-USERNAME/PlasmaPy.git
```
Tip

If you have trouble connecting to GitHub, you may need to add a new SSH key to your GitHub account.
Enter the newly created directory with:
```
cd PlasmaPy
```
Add a remote called upstream for PlasmaPy’s GitHub repository by using the following command.
```
git remote add upstream git@github.com:PlasmaPy/PlasmaPy.git
```
If you run git remote -v, you should see that origin corresponds to your fork and upstream corresponds to PlasmaPy’s GitHub repository.

Setting up a Python environment

If you plan to make multiple contributions, we recommend setting up a Python environment specifically for PlasmaPy. This section describes how to set up a Conda environment from the command line, which can be done after installing Conda or Anaconda Navigator as described in the section on getting Python. If you did not use Conda or Anaconda to install Python, we suggest using a virtual environment instead.

Tip

Using Conda/virtual environments helps avoid situations as in this xkcd comic.

Open a terminal.
Create a Conda environment named plasmapy-dev by running:
```
conda create -n plasmapy-dev python=3.11
```
The -n flag is used to specify the name of the environment. The 3.11 can be replaced with any version of Python from 3.9 to 3.11.
Activate the environment with:
```
conda activate plasmapy-dev
```
The conda activate command will need to be run every time you open a terminal, or can be added to the appropriate configuration file (i.e., .bashrc for bash or .zshrc for zsh).

Installing your clone of PlasmaPy

This section covers how to make an editable installation of your clone of PlasmaPy. Making the PlasmaPy installation editable means that if you modify the source code, then those changes will be included when you import plasmapy.

Open a terminal.
Navigate to the directory for your clone of PlasmaPy, which should be named PlasmaPy. For example, if you ran the git clone command in the ~/repos/ directory, then run:
```
cd ~/repos/PlasmaPy
```
Note

In Windows, the directory path will be C:Users<username>reposPlasmaPy.
If you created a Conda environment for contributing to PlasmaPy, activate it with:
```
conda activate plasmapy-dev
```
Run the command to install PlasmaPy for your operating system:
py -m pip install -e .[docs,tests]
python -m pip install -e .[docs,tests]
python -m pip install -e .[docs,tests]
Note

Replace py with python if you are not using conda.

The -e specifies that this will be an editable installation.
Tip

If the above command does not work, try running
```
pip install -r requirements.txt
```
This command will install that packages that PlasmaPy depends on, but not PlasmaPy itself.

Hint

If you import a package after doing an editable installation, then changes made after the import step will not be immediately available during a Python session. To re-import the package, use importlib.reload:

>>> from importlib import reload
>>> import plasmapy
>>> # now change the source code
>>> reload(plasmapy)

Installing pre-commit

PlasmaPy uses pre-commit to automate code quality checks and perform automated fixes. Because pre-commit checks are performed on GitHub, it is optional to set up pre-commit locally.

Tip

We recommend enabling pre-commit locally on your computer after you become comfortable with the code contribution workflow.

To enable pre-commit on your computer:

Open a terminal.
Navigate to the PlasmaPy/ directory that contains your clone of PlasmaPy’s repository. For example, if you cloned PlasmaPy into the ~/repos/ directory, then run:
```
cd ~/repos/PlasmaPy
```
If you created a Conda environment for PlasmaPy, activate it with:
```
conda activate plasmapy-dev
```

Make sure that pre-commit is installed by running:

py -m pip install pre-commit

python -m pip install pre-commit

python -m pip install pre-commit

Install pre-commit with:
```
pre-commit install
```

Note

Once pre-commit has been installed for a repository, pre-commit will run every time you try to commit a change. If any pre-commit checks fail, or if pre-commit changes any files, it will be necessary to redo git add on the changed files and git commit once again.

Tip

To commit a change without running pre-commit, use the -n or --no-verify flag with git.

Tip

To run pre-commit on all files, use

pre-commit run --all-files