From 6cc9e5551d6ac15c93b9e794a1bac1aa06251e68 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Sat, 14 Oct 2017 14:33:37 +0100 Subject: [PATCH 1/3] Pull in PR tutorial from https://github.com/SolarDrew/pyastro17-my-first-PR --- pull-request/README.md | 74 ++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 74 insertions(+) create mode 100644 pull-request/README.md diff --git a/pull-request/README.md b/pull-request/README.md new file mode 100644 index 0000000..a07744e --- /dev/null +++ b/pull-request/README.md @@ -0,0 +1,74 @@ +# Creating a Pull Request +This tutorial will walk you through making a pull request (often abbreviated to PR) to someone else's code project. + +To make a PR: +- Fork a repo +- Clone your fork of the repo +- Create a new branch in your local repo +- Make some changes to your local branch +- Push the changes to your fork +- Create PR + +## Fork a repo +Find and click the '**Fork**' button in the top-right of a GitHub repo that belongs to someone else - e.g.: SolarDrew/pyastro-my-first-PR. +This will make a copy of that repo, and that copy belongs to you. + +## Clone your fork of the repo +On your fork of the repo (<_your-username_>/pyastro17-my-first-PR), use the '**Clone or Download**' button to download the repo. +This is the same as you've done before with any of your other repos. + +#### Remotes +If you run `git remote -v` in your newly-cloned repo, you should see that you have one remote called 'origin'. +Again, this is the same as when you've pushed and pulled a repo to and from your GitHub account before. + +When your repo is a fork of someone else's, it's often useful to deal with that version as well as your own, in which case you may need to add it as another remote. +By convention, that remote is called 'upstream'. + +## Create a new branch in your local repo +#### Branches +Branches are a vital feature of git that allow different development tasks to be self-contained. +For instance, to add some new major functionality to a project, you will often want to create a separate branch of your repo. + +Splitting off in this way allows you to return to the original version if you need a clean working environment, or make other updates to that code. +You can also have many different branches at once, so several different features can be developed at the same time without interfering with each other. + +#### Working with branches +To see what branches exist in your repo, run `git branch`. +At the moment, this should just show 'master', which is the usual main branch and is the one branch created when you make a new repo. +You can also give this command an argument which is the name of a new branch to create. +So in this repo, run `git branch new_contributor` to make a new branch called 'new_contributor'. +This creates a branch but you are still working in the master branch. +To switch to your new branch, run `git checkout new_contributor`. + +## Make some changes to your local branch +Make some changes to some document on your local branch of the repo. +For this example, add your name and GitHub username to the contributors list at the bottom of this file (README.md). +Commit your changes with `git add` and `git commit`. + +## Push the changes to your fork +This is very similar to pushing you've done before, but now you need to take branches into account. + +#### `git push` syntax +Up until now we have been doing `git push origin master`. +What this actually does is tell git to push your current branch of the local repo (which has been master until this example) to the 'master' branch of the 'origin' remote. + +In this case we've been working in a different branch, 'new_contributor', so we don't want to push to the master branch. +Instead we should push to the new_contributor branch on origin, if it exists. +If not, we should push to it anyway and git will create it for us, so the command is the same either way: +`git push origin new_contributor` + +## Create PR +On the GitHub page for your fork of the repo, you should see drop-down menu that says '**Branch: master**' and a button next to it saying '**New pull request**'. +Select the new_contributor branch from the drop-down menu and then click the button. +You should then get a page telling you what the base fork and branch are (into which you want your code to be merged), and the fork and branch are (that you're trying to merge). +For this example those should be SolarDrew/pyastro17-my-first-PR master and <_your-username_>/pyastro17-my-first-PR new_contributor. +This page also lets you give your PR a title and a description. + +When you've added these, click the big green '**Create pull request**' button and you're done! +Now I, as the owner of the original repo, have the option to accept or refuse the changes you've made to the code. + +## Contributors + +- Drew Leonard (SolarDrew) +- Benjamin Winkel (bwinkel) +- Esteban Morales (eztean) \ No newline at end of file From 02393f3f37d540250312d95acf82e5810d611ab1 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Sat, 14 Oct 2017 16:53:10 +0100 Subject: [PATCH 2/3] Updates and expansion on tutorial --- pull-request/README.md | 72 +++++++++++++++++++++++++++--------------- 1 file changed, 46 insertions(+), 26 deletions(-) diff --git a/pull-request/README.md b/pull-request/README.md index a07744e..8171c03 100644 --- a/pull-request/README.md +++ b/pull-request/README.md @@ -1,8 +1,10 @@ # Creating a Pull Request -This tutorial will walk you through making a pull request (often abbreviated to PR) to someone else's code project. +This tutorial will walk you through how to request that someone else pulls your changes to their code into their project. +This is called a **pull request**, usually abbreviated to PR. +It is assumed that you are comfortable with using the fundamental git commands (`git add`, `git commit`, etc.) at a command prompt, and that you are familiar with pushing and pulling repositories to and from GitHub. -To make a PR: -- Fork a repo +These are the steps necessary to make a PR, each of which will be described in more detail below: +- Fork a repository - Clone your fork of the repo - Create a new branch in your local repo - Make some changes to your local branch @@ -10,65 +12,83 @@ To make a PR: - Create PR ## Fork a repo -Find and click the '**Fork**' button in the top-right of a GitHub repo that belongs to someone else - e.g.: SolarDrew/pyastro-my-first-PR. +Find and click the '**Fork**' button in the top-right of a GitHub repo that belongs to someone else - e.g.: https://github.com/PlasmaPy/PlasmaPy-Tutorials. This will make a copy of that repo, and that copy belongs to you. ## Clone your fork of the repo -On your fork of the repo (<_your-username_>/pyastro17-my-first-PR), use the '**Clone or Download**' button to download the repo. +On your fork of the repo (<_your-github-username_>/PlasmaPy-Tutorials), use the '**Clone or Download**' button to download the repo. This is the same as you've done before with any of your other repos. #### Remotes -If you run `git remote -v` in your newly-cloned repo, you should see that you have one remote called 'origin'. +If you run the command `git remote -v` in your newly-cloned repo, you should see that you have one remote called **'origin'**. Again, this is the same as when you've pushed and pulled a repo to and from your GitHub account before. When your repo is a fork of someone else's, it's often useful to deal with that version as well as your own, in which case you may need to add it as another remote. -By convention, that remote is called 'upstream'. +By convention, that remote is called **'upstream'**. +To do this, you can run `git remote add upstream <_url-of-remote-repo_>`. +In this case the URL for the upstream remote would be https://github.com/PlasmaPy/PlasmaPy-Tutorials. ## Create a new branch in your local repo +This step is not strictly necessary to make a PR, but is highly recommended as part of the git workflow in general, so we shall take the time to go through it here. + #### Branches Branches are a vital feature of git that allow different development tasks to be self-contained. For instance, to add some new major functionality to a project, you will often want to create a separate branch of your repo. - -Splitting off in this way allows you to return to the original version if you need a clean working environment, or make other updates to that code. +Splitting off in this way allows you to work on the new feature without affecting the original code at all until you are ready to merge them together. +This means you can return to the original version if you need a clean working environment, or make other updates to that code. You can also have many different branches at once, so several different features can be developed at the same time without interfering with each other. #### Working with branches -To see what branches exist in your repo, run `git branch`. +To see what branches exist locally in your repo, run `git branch`. At the moment, this should just show 'master', which is the usual main branch and is the one branch created when you make a new repo. You can also give this command an argument which is the name of a new branch to create. So in this repo, run `git branch new_contributor` to make a new branch called 'new_contributor'. -This creates a branch but you are still working in the master branch. +This creates a branch but if you run `git branch` again, you will see that you are still working in the master branch. To switch to your new branch, run `git checkout new_contributor`. +Similarly, from there you can return to your original branch with `git checkout master`. ## Make some changes to your local branch Make some changes to some document on your local branch of the repo. -For this example, add your name and GitHub username to the contributors list at the bottom of this file (README.md). +For this example, add your name and GitHub username to the contributors list at the bottom of this file (pull-request/README.md). Commit your changes with `git add` and `git commit`. +Once you've done this you can see the separation of branches by checking out your master branch again and inspecting it. +If you look at the commit history (`git log`) and open the file again, you will see that the commit you just made and the corresponding changes are no longer there. +Returning to the new_contributor branch restores the commit and the changes. +Don't forget to do this before moving on with the tutorial. + +### Update your local branch +This is also not strictly necessary but is often a good idea. + +It is important to remember that while we are making changes in our branch of our fork, it is very likely that the main project branch (`upstream/master`) is also changing. +If we don't to anything to account for this, it may cause merge conflicts when we make our PR, which will delay our contribution. +It therefore often makes things easier (particularly for the maintainer of the main code project) for you to pull in any changes to upstream and resolve any conflicts with your changes locally. +Doing this means that when you make your PR, the only differences between your branch and the original are the changes you wish to submit, which is as it should be. +You can do this with `git pull upstream master`. +Note that this pulls the master branch of the upstream repo and merges it into _your current local branch_ - don't make the common mistake of thinking this will update your local master branch, unless that is the branch you have checked out when you run the command. +See below for a bit more on this syntax, which is the same as for `git push`. + ## Push the changes to your fork -This is very similar to pushing you've done before, but now you need to take branches into account. +This is very similar to pushing you will have done before, but now you need to take branches into account. #### `git push` syntax -Up until now we have been doing `git push origin master`. -What this actually does is tell git to push your current branch of the local repo (which has been master until this example) to the 'master' branch of the 'origin' remote. +Up until now you have likely been doing `git push origin master`. +What this actually does is tell git to push your current branch of the local repo (which is master by default) to the 'master' branch of the 'origin' remote. -In this case we've been working in a different branch, 'new_contributor', so we don't want to push to the master branch. -Instead we should push to the new_contributor branch on origin, if it exists. -If not, we should push to it anyway and git will create it for us, so the command is the same either way: -`git push origin new_contributor` +In this case we've been working in a different branch, `new_contributor`, so we don't want to push to the master branch. +Instead we should push to the `new_contributor` branch on origin, if it exists. +If not, we should push to it anyway and git will create it for us, so the command is the same either way: `git push origin new_contributor`. ## Create PR On the GitHub page for your fork of the repo, you should see drop-down menu that says '**Branch: master**' and a button next to it saying '**New pull request**'. -Select the new_contributor branch from the drop-down menu and then click the button. -You should then get a page telling you what the base fork and branch are (into which you want your code to be merged), and the fork and branch are (that you're trying to merge). -For this example those should be SolarDrew/pyastro17-my-first-PR master and <_your-username_>/pyastro17-my-first-PR new_contributor. -This page also lets you give your PR a title and a description. +Select the `new_contributor` branch from the drop-down menu and then click the button. +You should then get a page telling you what the base fork and branch are (into which you want your code to be merged), and what the fork and branch are (that you're trying to merge). +For this example those should be `PlasmaPy/PlasmaPy-Tutorials master` and `<_your-username_>/PlasmaPy-Tutorials new_contributor`. +This page also lets you give your PR a title and a description, which you should use to make clear to other developers what the purpose of the PR is. When you've added these, click the big green '**Create pull request**' button and you're done! -Now I, as the owner of the original repo, have the option to accept or refuse the changes you've made to the code. +Now I, or another maintainer of the original repo, have the option to accept or refuse the changes you've made to the code. ## Contributors - Drew Leonard (SolarDrew) -- Benjamin Winkel (bwinkel) -- Esteban Morales (eztean) \ No newline at end of file From 0484af8c9c7d496dd6dcd7772f105f0628cf34b5 Mon Sep 17 00:00:00 2001 From: Drew Leonard Date: Mon, 13 Nov 2017 17:33:15 +0000 Subject: [PATCH 3/3] Make tweaks to tutorial from Nick's comments --- pull-request/README.md | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/pull-request/README.md b/pull-request/README.md index 8171c03..05d00a2 100644 --- a/pull-request/README.md +++ b/pull-request/README.md @@ -2,6 +2,8 @@ This tutorial will walk you through how to request that someone else pulls your changes to their code into their project. This is called a **pull request**, usually abbreviated to PR. It is assumed that you are comfortable with using the fundamental git commands (`git add`, `git commit`, etc.) at a command prompt, and that you are familiar with pushing and pulling repositories to and from GitHub. +If you are completely new to git, you may want to first find and go through a tutorial to learn these fundamental commands before continuing with this one. +https://try.github.io/ and https://git-scm.com/book/en/v1/Git-Basics are two such tutorials, but there are plenty of others out there. These are the steps necessary to make a PR, each of which will be described in more detail below: - Fork a repository @@ -17,6 +19,7 @@ This will make a copy of that repo, and that copy belongs to you. ## Clone your fork of the repo On your fork of the repo (<_your-github-username_>/PlasmaPy-Tutorials), use the '**Clone or Download**' button to download the repo. +Alternatively you can do this manually at the command line with the syntax `git clone https://github.com/<_your-github-username_>/<_name-of-repo_>.git` or `git clone /<_name-of-repo_>.git`. This is the same as you've done before with any of your other repos. #### Remotes @@ -30,6 +33,8 @@ In this case the URL for the upstream remote would be https://github.com/PlasmaP ## Create a new branch in your local repo This step is not strictly necessary to make a PR, but is highly recommended as part of the git workflow in general, so we shall take the time to go through it here. +You can do this with the command `git branch new_contributor` and then `git checkout new_contributor`. +These commands are explained below. #### Branches Branches are a vital feature of git that allow different development tasks to be self-contained.