Getting Ready to Contribute

Introduction

Thank you for considering contributing to PlasmaPy — we really appreciate it! 🌱 This page describes how 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 during our community meetings.

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.

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 security and authentication.

Getting set up to contribute

Clone the repository

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
```
Important

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.

Install uv

uv is an extremely fast Python package and project manager used ubiquitiously during PlasmaPy development.

Open a terminal and follow these instructions to install uv.

Install Nox

Nox is an automation tool used by PlasmaPy to run tests, build documentation, and perform code quality checks. Install Nox with:

uv tool install nox

Install pre-commit

pre-commit is a framework for running code quality checks and performing automated fixes. Install pre-commit with:

uv tool install pre-commit

Create a virtual environment

To create a virtual environment, run:

uv venv

The output will provide a command to activate the virtual environment. The command is typically source .venv/bin/activate on Linux, macOS, and WSL (for POSIX compliant shells like zsh, bash, and sh); and .venv\Scripts\activate for Windows PowerShell (which might need to be run as an administrator).

To sync the virtual environment with the development environment, run:

uv sync

And with that, you’re all set up to contribute to PlasmaPy! ✨️

Tip

To install PlasmaPy and developer dependency groups into an activated virtual environment not managed by uv, enter the top-level directory of your local clone of PlasmaPy and run:

python -m pip install -e . --group dev

The -e indicates that the installation is editable.