|
| 1 | +# Intro to PRs |
| 2 | + |
| 3 | + |
| 4 | + |
| 5 | +You can use the following guide to learn how and why to create a pull request. |
| 6 | + |
| 7 | +## What is a pull request? |
| 8 | + |
| 9 | +A pull request is a way to suggest changes to a repository. When you create a pull request, you propose your changes and request that someone review and pull in your contribution and merge them into their branch. Pull requests show differences between the content from both branches and the changes are visible in the repository. |
| 10 | + |
| 11 | +<!-- TODO: Add information on PRs and forks. --> |
| 12 | + |
| 13 | +## Set up your environment |
| 14 | + |
| 15 | +### Create a local copy of the repository |
| 16 | + |
| 17 | +Copy the following file to a new Git repo. |
| 18 | + |
| 19 | +```bash |
| 20 | +cd ~/source/repos |
| 21 | +git init my-first-pr |
| 22 | +cd my-first-pr |
| 23 | +cp ~/Downloads/README.md . |
| 24 | +``` |
| 25 | + |
| 26 | +**IMPORTANT:** Please ensure you continue working on the file copy and not the original. |
| 27 | + |
| 28 | +### Create an empty repository on GitHub |
| 29 | + |
| 30 | +1. Go to [GitHub](https://github.com) and sign in. |
| 31 | +2. In the upper-right corner of any page, select `➕`, and then select `New repository`. |
| 32 | +3. Name your repository `my-first-pr`. |
| 33 | + **IMPORTANT:** Do not initialize the repository with a `README`, `.gitignore`, or license. |
| 34 | +4. Note the name of your repository `URL` here: **<URL>** |
| 35 | + You'll need this information later. |
| 36 | + |
| 37 | +### Add the remote repository |
| 38 | + |
| 39 | +1. In the terminal, add the URL of the repository you created on GitHub as the remote repository. |
| 40 | + |
| 41 | +```bash |
| 42 | +git remote add origin <URL> |
| 43 | +``` |
| 44 | + |
| 45 | +2. Check that the remote repository was added. |
| 46 | + |
| 47 | +```bash |
| 48 | +git remote -v |
| 49 | +``` |
| 50 | + |
| 51 | +3. Consider why it does not provide a URL for pull, only `push` and `fetch`? |
| 52 | + |
| 53 | +--- |
| 54 | + |
| 55 | +4. Push the local repository to the remote repository. |
| 56 | + |
| 57 | + ```bash |
| 58 | + git push -u origin main |
| 59 | + ``` |
| 60 | + |
| 61 | +5. Refresh the GitHub page for your repository. You should see this `README.md` file. |
| 62 | + |
| 63 | +### Why are pull requests called "Pull Requests"? (wrong answer) |
| 64 | + |
| 65 | +Pull requests are so named basically because you are asking to _pull_ changes from a remote to your local repository. And that's because you have to ask permission to copy changes out of the repository, even if you have read access to that repository. |
| 66 | + |
| 67 | +<!--TODO: This answer is SO wrong, I think we need to fix it! --> |
| 68 | + |
| 69 | +### Create a local branch |
| 70 | + |
| 71 | +You read the definition above, and you can't believe they got it this wrong. The name `Pull Request` can be misleading, but come on! |
| 72 | + |
| 73 | +You decide to fix the definition above, but BEFORE you do that, you need to create a new branch to work on. |
| 74 | + |
| 75 | +1. Create a new branch and switch to it. |
| 76 | + |
| 77 | +```bash |
| 78 | +# Older style: |
| 79 | +git checkout -b fix/pr-definition |
| 80 | +# Or, newer style: |
| 81 | +git switch -c fix/pr-definition |
| 82 | +``` |
| 83 | + |
| 84 | +2. Edit this file and address the two TODO items in two separate commits. |
| 85 | + |
| 86 | +```bash |
| 87 | +git commit -am "Add forks to the PR definition" |
| 88 | +git commit -am "Give correct reason to why PRs are named that" |
| 89 | +``` |
| 90 | + |
| 91 | +3. Check on GitHub whether the branch exists there or not. Does it? Why or why not? |
| 92 | +4. You may think it is because you haven't pushed to the branch yet, so go ahead and try to push the branch to the remote repository. |
| 93 | + |
| 94 | +```bash |
| 95 | +git push |
| 96 | +# or in full |
| 97 | +git push origin fix/pr-definition |
| 98 | +``` |
| 99 | + |
| 100 | +You probably got a similar error to this: |
| 101 | + |
| 102 | +```text |
| 103 | +fatal: The current branch fix/pr-definition has no upstream branch |
| 104 | +``` |
| 105 | + |
| 106 | +5. What does this error mean? Why did it happen? Git explains how to fix it by running a command that will: |
| 107 | + |
| 108 | + 1. Create a new branch on the remote repository with the same name as the local branch (if the remote branch doesn't already exist). |
| 109 | + 2. Set the local branch to track the remote branch. |
| 110 | + 3. Push the local branch to the remote repository. |
| 111 | + |
| 112 | +7. Run the command that Git suggests to fix the error. There is also a shorthand for this command: |
| 113 | + |
| 114 | +```bash |
| 115 | +git push -u origin fix/pr-definition |
| 116 | +``` |
| 117 | + |
| 118 | +7. Refresh the GitHub page for your repository. You should see the new branch there. GitHub will also suggest that you create a pull request. Do you see that? |
| 119 | + |
| 120 | +### Create a pull request |
| 121 | + |
| 122 | +1. Select `Compare & pull request`. |
| 123 | +2. Note that the base repository and compare branch are correct. |
| 124 | +3. Add a title and description for your pull request. Here is an example of a high-quality pull request description: |
| 125 | + |
| 126 | + ```markdown |
| 127 | + Title: Fix PR definition |
| 128 | + Description: This pull request fixes the definition of a pull request. It adds information about forks and corrects why pull requests are called "pull requests". |
| 129 | + ``` |
| 130 | + |
| 131 | +4. Select `Create pull request`. |
| 132 | + |
| 133 | +### Review and merge a pull request |
| 134 | + |
| 135 | +1. Go to the `Pull requests` tab on the repository page. |
| 136 | +2. Select the pull request you created. |
| 137 | +3. Review the changes in the pull request. You can see the commits that were added to the branch. You can also view the changes in the `Files changed` tab. |
| 138 | +4. Add a comment to the pull request. Please feel free to ask for more information, suggest changes, or approve the pull request. |
| 139 | +5. Select `Merge pull request` to merge the changes into the `main` branch. |
| 140 | + |
| 141 | +Notice that GitHub suggests that you delete the branch after merging. This is a good practice because it keeps your repository clean and easy to navigate. It is part of a Git workflow called `GitHub flow`. |
| 142 | + |
| 143 | +### Optional: Fork someone else's repository and create a pull request |
| 144 | + |
| 145 | +If you are doing this in class, you can fork the repository of the person sitting next to you. If you are doing this on your own, you can fork a friend's or colleague's repository. |
| 146 | + |
| 147 | +When you fork their repo, examine their definition and try to improve on it, then create a pull request to suggest your changes on **their** repository. |
0 commit comments