Getting Ready to Contribute
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.
Opening a terminal
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.
In the Finder, go to Applications. Enter the Utilities folder and double click on Terminal.
Open a terminal by using Ctrl + Alt + T.
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).
Using git and GitHub
Sign up on GitHub for a free account.
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 "firstname.lastname@example.org"
You may also set your default editor with a command like the following, where
notepadcan 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.
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
mkdir ~/repos cd ~/repos
Clone the PlasmaPy repository with the following command, replacing
YOUR-USERNAMEwith your GitHub username. This will create a subdirectory called
PlasmaPy/containing your local clone of the repository.
git clone email@example.com:YOUR-USERNAME/PlasmaPy.git
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:
git remote add upstream firstname.lastname@example.org:PlasmaPy/PlasmaPy.git
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.
Using Conda/virtual environments helps avoid situations as in this xkcd comic.
Create a Conda environment named
conda create -n plasmapy-dev python=3.11
-nflag is used to specify the name of the environment. The
3.11can be replaced with any version of Python from 3.9 to 3.11.
Activate the environment with:
conda activate plasmapy-dev
conda activatecommand will need to be run every time you open a terminal, or can be added to the appropriate configuration file (i.e.,
.bashrcfor bash or
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
Navigate to the directory for your clone of PlasmaPy, which should be named
PlasmaPy. For example, if you ran the
git clonecommand in the
~/repos/directory, then run:
In Windows, the directory path will be
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]
pythonif you are not using conda.
-especifies that this will be an editable installation.
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.
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