Code Contribution Workflow
Issues labeled as a good first issue are a great place to get started with contributing.
Making a code contribution
Create a new branch
Navigate to the
PlasmaPy/directory that contains the clone of your repository.
In the terminal, run:
If the output ends with
nothing to commit, working tree clean, then proceed to the next step.
git statusshows that any files are listed under
Changes not staged for commitor
Changes to be committed, then do one of the following before proceeding to the next step:
Use git stash to temporarily file away the changes, or
git reset --hardto permanently remove all changes to tracked files and return to the previous commit.
If there are untracked files present, then you may delete the untracked files, add and commit changes, or proceed to the next step.
Download the current status of PlasmaPy’s GitHub repository and your fork by running:
git fetch --all
Create and switch to a new branch by running:
git checkout -b new-branch-name upstream/main
new-branch-nameis changed to the name of the new branch. Here
upstreamis the name of the remote and
mainis the name of the original branch which the new branch will be based off of.
Use descriptive branch names like
git push --set-upstream origin new-branch-name
Add and commit changes
Next we can go through the cycle of making changes, which is usually
repeated multiple times. To get a better idea of what is being done in
each step, try running
Edit a file and save the changes.
In a terminal, navigate to the directory with the changed file and run:
git add filename
filenameis replaced with the name of the edited file(s). Use
git add *to add all files in the directory (except for files specified in
.gitignore. This step lets us line up the changes that we want to record as a snapshot in history.
To commit the changes, run:
git commit -m "<commit message>"
<commit message>is replaced with a descriptive commit message such as
"Add gyroradius function". Committing a change is like preserving a snapshot of what each file looks like at this point in history.
If it has been installed, pre-commit will perform automated checks and possibly auto-fixes. If pre-commit fails, then it’ll be necessary to fix any remaining problems and do the
git commitsteps once more. Try using
git diff --cachedto view the changes, and ↑ and ↓ to scroll through previous commands in a terminal.
To push the changes to GitHub, run:
Try using the
git status command after each step to get a
better idea of what is happening.
git workflow can be thought of as the process of mailing a
git addis like packing the contents of a package into a box. This step allows you to choose which changes to include in the next commit.
git commitis like sealing and labeling the package, and putting it in the outgoing mail.
git pushis like sending the package off to its destination (i.e., GitHub).
Creating a pull request
git pushto make sure that branch on GitHub is up-to-date.
Go to PlasmaPy’s GitHub repository.
If you recently pushed new changes, a pale yellow box will appear near the top of the screen. In that box, click Compare & pull request.
If you did not recently push any new changes, click on New pull request and then the link saying “compare across forks.” Select
PlasmaPy/PlasmaPyfor “base repository” and
mainfor “base”. Choose your fork of PlasmaPy for “head repository” and the name of the branch for “compare”. Then click on Create pull request.
Add a descriptive title, such as
Add a function to calculate particle gyroradii.
Write a description for the pull request (PR). Describe the changes, and why they are being made. Include information that you think would be helpful for reviewers, future users, and future contributors..
If your pull request will resolve an issue, include
Closes #ISSUE-NUMBERin the pull request description, where
ISSUE-NUMBERis replaced with the number of the issue.
Select Create pull request.
If the pull request isn’t ready for review, select the ▼ next to Create pull request to enable you to create a draft pull request instead.
Add a changelog entry, except for minor changes like typo fixes.
At this stage, a reviewer will perform a code review, unless it has been marked as a draft pull request. Thank you for contributing!
Pulling changes from GitHub
If your branch changes on GitHub, run
to pull the changes from GitHub to your computer. If you’d like to pull
the changes from the
main branch, instead run
git pull upstream main
If any of the changes conflict with each other, it will be necessary to resolve the merge conflict.
After the pull request has been created, it can be updated by
git push to update the corresponding branch on
If this is your first contribution, please add yourself to the author
CITATION.cff (which uses Citation File Format) to make
sure that you get credit for your contribution. The entry should be
of the form:
- given-names: <given names>
family-names: <family names>
alias: <GitHub username>
All fields are optional except
alias, which is your GitHub
username. We encourage contributors to sign up for an ORCID iD: a
unique, persistent identifier used by researchers, authors, and open