Code Contribution Workflow
Introduction
This page describes the workflow for making a contribution to PlasmaPy via a pull request. This page assumes that you have finished the steps for Getting Ready to Contribute.
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. Thank you for contributing!
Tip
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.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
where
new-branch-name
is changed to the name of the new branch. Hereupstream
is the name of the remote andmain
is the name of the original branch.Tip
Use descriptive branch names like
update-contribution-workflow
.Connect your local branch to your fork of PlasmaPy on GitHub by running:
git push --set-upstream origin new-branch-name
Add and commit changes
Next we can go through the cycle of making changes, which can be repeated multiple times.
Edit a file and save the changes.
In a terminal, run:
git add filename
where
filename
is replaced with the name of the edited file(s). Usegit 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>"
where
<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 make some automated changes. If pre-commit fails, then it’ll be necessary to do the
git add
andgit commit
steps once more.To push the changes to GitHub, run:
git push
Tip
Try using the git status
command after each step to get a better
idea of what is happening.
Note
The git
workflow can be thought of as the process of mailing a
package.
git add
is 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 commit
is like sealing and labeling the package, and putting it in the outgoing mail.git push
is like sending the package off to its destination (i.e., GitHub).
Creating a pull request
Run
git push
to 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.
Note
If you did not recently push any new changes, click on New pull request and then the link saying “compare across forks.” Select
PlasmaPy/PlasmaPy
for “base repository” andmain
for “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. Describe the changes, and why they are being made. Include information that you think would be helpful for reviewers, future users, and future contributors..
Tip
If your pull request will resolve an issue, include
Closes #ISSUE-NUMBER
in the pull request description, whereISSUE-NUMBER
is replaced with the number of the issue.Select Create pull request.
Tip
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.
Note
After the pull request has been created, it can be updated by using
git push
to update the corresponding branch on GitHub.If this is your first contribution, please add yourself to the author list in
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> affiliation: <affiliation> orcid: https://orcid.org/<ORCiD-iD> alias: {missing_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 source contributors.
At this stage, a reviewer will perform a code review, unless it has been marked as a draft pull request. Thank you for contributing!