[Task 1]: Submitting your first pull request
cjtu opened this issue · comments
Your First Open Source Contribution
These steps will walk you through making your first contribution to a public GitHub repository by adding your name to the Plutopy CONTRIBUTORS.md file. This tutorial is adapted from an excellent teaching repository, first-contributions.
First time using GitHub?
You will need to sign up for a free account here.
First time using Git?
This tutorial involves use of Git terminal commands. To check if you have Git on Mac/Linux, open a terminal and type git --version. If you need to install Git, you can learn how to do so here.
If this is your first time using Git, you will need to configure it so that your work is properly attributed to you. Make sure you use the same email that you used to sign up for GitHub.
git config --global user.name "Firstname Lastname"
git config --global user.email "email@domain.com"Fork this repository
Fork this repository by clicking on the fork button on the top of the main repository page here. You may want to open this in a new window to keep these instructions up!
Clicking fork will create a copy of this repository in your GitHub account.
Clone the repository
Now you need to clone your forked repository to your machine. Go to your GitHub account, open the forked repository, click on the clone or download button.
Next, copy the url you see (you should see your GitHub username in the url).
Open a terminal, navigate to where you want to clone the repository, and run the following git command:
git clone "url you just copied"
where "url you just copied" (without the quote marks) is the url to your fork of this project.
For example:
git clone https://github.com/this-is-you/plutopy.git
where this-is-you is your GitHub username.
This copies your forked Plutopy repository from the GitHub website to your machine!
Create a branch
Enter the repository directory on your computer (if you are not already there):
cd plutopy
Now create a branch using the git checkout command:
git checkout -b <new-branch-name-here>
The name of the branch should describe the change you are planning on making. For example:
git checkout -b add-christian-to-contributors
Make necessary changes and commit those changes
Now let's see what is in the directory that you just cloned/
ls
Notice the CONTRIBUTORS.md file? This is the file we want to add your name to.
Open CONTRIBUTORS.md file in any text editor on your computer (you can use a terminal text editor like emacs if you are familiar, but NotePad and TextEdit will work fine as well). With the file open, add your name to the middle of the list somewhere. Don't add it at the beginning or end of the file. Now, save the file and return to the terminal.
If you are in the plutopy project directory and execute the command git status, you'll see there are changes.
Add those changes to the branch you just created using the git add command:
git add CONTRIBUTORS.md
Run git status again and you will see that your changes are staged and ready to commit.
In Git, each change to a repository is locked in with a "commit" which also acts like a snapshot of the repository at a certain point in time. Now commit your change using the git commit command:
git commit -m "Add <your-name> to contributors list"
replacing <your-name> with your name. This message describes the change you made so that it can be easily found later.
Push changes to GitHub
Push your changes using the command git push:
git push origin <add-your-branch-name>
replacing <add-your-branch-name> with the name of the branch you created earlier. You will likely need to enter your GitHub username and password.
Submit your changes for review
If you go to your forked repository on GitHub, you'll see a Compare & pull request button. Click on that button.
This is where you would normally add a description of the changes in your pull request. You can reference an issue that you addressed by typing #num where num is the number of the issue. Your description could look something like this:
Finished issue #1 by adding <my-name> to the contributors list.
Now submit the pull request.
Review
The pull request is the most common way of making a contribution to an open-source repository. Once a plutopy maintainer sees your request, they will review your changes. If anything needs to be updated before your change is added to the main repository, they will comment on your request and let you know.
You will get a notification once the changes have been merged, at which point you should see your name in the main plutopy repository here!
Where to go from here?
Great job submitting your first open source contribution! You have now seen the common fork -> clone -> edit -> commit -> Pull request workflow used by most open source GitHub repos.
While your contribution is being reviewed, a good next step would be to join the plutopy Gitter, a chat where plutopy members can talk about issues and open science. Next, you can check out the plutopy contributing guidelines which have some next steps for continuing to learn with plutopy (see below).
Contributing guidelines
Many open source repositories will have contributing guidelines in a file called CONTRIBUTING.md. This file provides general info and guidelines to follow to get started contributing to a repository and to make sure your contributions meet the repository's standards. The contributing guidelines for this project can be found at CONTRIBUTING.md. Review them and follow the instructions to get a plutopy environment set up on your computer.
GitHub Issues
Issues can be opened by anyone to communicate bugs or feature requests to the maintainers of a GitHub repo. To contribute to an open source repository, you will generally find an issue you would like to work on, comment on the issue to let the maintainers know that you are working on it, and then do exactly as we did above (fork, clone, edit, commit) and submit your fix as a pull request. Once you have read the contributing guidelines, check out the issue board to find a new tutorial to work on.