⬇️ Creating a Pull Request ⬇️ - AideenM12/retro-gaming-hackathon GitHub Wiki
❓ ❓ The thoughts.... In this post, we are going to look at creating a pull request, so that you can submit your feature up to the main repository (henceforth called the Upstream Remote), for review by your teammates/colleagues, before being merged into same. For most, the upstream remote will be the project that gets submitted for assessment and will be the project for which our deployed production environment exists. With that in mind, it is so important to ensure that the features pushed and merged into the Upstream Remote are secure and bug free! 🔒🐞
📱 <--- When you see this emoji followed by a number in the below steps, it means that there is a subsequent screenshot shared in the Thread of the Post!
🧠🤔 How to create a Pull Request? 🤔🧠 Follow the steps below 👇:
- Go to https://github.com/original-user/repo-name (replace "original-user" with the account holder's username, and "repo-name" with the name of the actual repo 😉) or go direct to your own forked repo, and then follow the steps below!
- From here, click on the "Pull requests" tab, located in the top navigational menu of the repository. 📱#1
- If you have developed a feature onto a branch, then on this tab you will see a green "Compare & pull request" button, with some information to the left detailing the branch-name and some base information. Click this button to start the process for submitting your 🔃 Pull request!📱#2
- You will be greeted with the "Open a pull request" screen! Kind of exciting stuff if this is the first time you are doing one. And it can be a bit unnerving too. 🙈 But don't fret.....we can go through this screen. 📱#3
- At the top, you will see a small context section. This is telling us that we are trying to send our code into the Upstream Remote, and it is coming from our branch. These two entities are being compared, and if there are no conflicts detected, you should see a little green message telling you "Able to merge". <-- We don't want to automatically merge though, we want our colleagues to review the code to be absolutely sure that it is good for merging! 😅
(If on your own forked repo, make sure that on the left the Upstream Repository Main/Master is selected, and on the right your Forked Repository Branch is selected)
- Directly under we have the "Pull request form".
- The title of this should already be filled out for you, and it normally contains the most recent commit message. This can be changed to reflect anything you want, so feel free to change it, especially if the feature is a large one.
- We then have our "Leave a comment" field, and this is where we detail our feature notes. For good measure, it's best to see a screenshot of one of these::iphone:#4. But the premise of these is to be as descriptive as is necessary. This form field can be formatted using the formatting bar, can contain lists and even images (including .gif format)! When you are finished writing up what you want, you can then click on "Preview" to do exactly as that states on the tin! Preview the Pull request comment. 😄
This little comment box actually is a markdown editor! So all the normal markdown formatting things will work here 😉 For reference, here is the godmode-cheatsheet 
for Github Markdown: https://github.com/adam-p/markdown-here/wiki/Markdown-Cheatsheet
-
Clicking on "Create pull request", will finalise the title, comment & screenshots etc of the "Pull request form", and bundle them up into a Pull request with all your latest commits and code from the branch.
This doesn't automatically merge the code into the Upstream Repository, instead it goes into a list of Pull requests for your colleagues to see and review. Don't be disheartened if your colleagues leave you feedback! This entire process is dependent on good communication and teamwork. 🤜🤛 You will be redirected into the specific "Pull request" that you just added, and from here you can select a reviewer or leave your colleagues be a reviewer for you at their leisure.:iphone:#5
- To select a reviewer, click on the ⚙️ gear-icon in the top right "Reviewers" section, and then select from the appropriate accompanying dropdown. As you can see here I've selected my friend and collaborator, Monika, for this demonstration. 😄
Side note: 📓
If you get feedback to change something in the PR, you don't need to re-create a new branch, and set the upstream and then create another PR to suit! Instead, just go to the existing branch, (if not already on the branch use git checkout branch-name in the terminal to switch to it), make the appropriate changes based on the feedback, and then add, commit & push! Github will auto-update your PR for you! Which is so damn handy and efficient.... ⚡ 
⚡
Side note #2: 📓
If at any stage you are asked to "Resolve Conflicts", go to your branch, (if not already on the branch use git checkout branch-name in the terminal to switch to it), and then run this command: git pull upstream main <-- change "main" for "master" depending on the Upstream Repository's primary branch naming convention your team decided on!
Running this command will pull all the current deployed code down to your branch from the Upstream Repository, and you will then be tasked with removing the Merge Conflicts. Merge Conflicts are places in your files where code already exists, and we, in our PR, are asking Git to put code on those lines also. You will need to go to the affected files, (Gitpod/vsCode and any IDE worth their salt should show you where these are), and then look for the conflict markers. For simplicity sake, these are denoted by chevron arrows:
<<<<<<< >>>>>>>
Inside those markers you will have "conflict dividers", these are denoted with ======= equal symbols! Above the conflict divider is the code from the Upstream Repository, below, is the code we want to supplant in the same occupied space as that code. We need to remove the conflict markers and divider, and then decide on what to do with the code 😅 This could mean removing, appending, mutating, keeping both etc.....but it is a bit of work, so do go over this with someone in your team, or again ask in the channel for some guidance! When you are happy with the code, add, commit & push to the branch!
Appropriate Screenshots to accompany above 📱 mentions of a screenshot, can be found here: https://code-institute-room.slack.com/archives/CDAFARB71/p1623850926008600?thread_ts=1623850885.008300&cid=CDAFARB71