Merge pull request #25 from dfe-analytical-services/newfeature/pull-r…

…equests

Newfeature/pull requests

_quarto.yml

@@ -52,20 +52,24 @@ website:
     contents:
       - href: index.qmd
         text: Welcome
-      - href: pre-requisites.qmd
+      - href: prerequisites.qmd
       - section: "Git basics refresher"
         contents:
           - git-refresher/clone-a-repo.qmd
           - git-refresher/making-a-branch.qmd
           - git-refresher/recording-changes.qmd
           - git-refresher/syncing-changes-to-remote.qmd
           - git-refresher/moving-between-branches.qmd
+          - git-refresher/making-more-branches.qmd
+
       - section: "GitHub DevOps basics refresher"
         contents:
           - github-devops-refresher/navigating-branches.qmd
           - github-devops-refresher/viewing-files.qmd
           - github-devops-refresher/editing-files.qmd
           - github-devops-refresher/viewing-history.qmd
+          - github-devops-refresher/pull-requests.qmd
+          - github-devops-refresher/reviewing-pull-requests.qmd
       - glossary.qmd
 
 format:

git-refresher/making-more-branches.qmd

@@ -0,0 +1,90 @@
+---
+title: "Making more branches"
+---
+
+This section will guide you through how to create more branches, taking the main branch you created as a base.
+
+When you create a Git project, it will automatically create a "main" (sometimes "master") branch for you. This is where the code that has been QA'd and you are happy with should sit.
+
+It is good practice to create a branch whenever you have a change to make to your work. Having two branches means that if anything goes wrong in the "development branch", the "main" branch is still unaffected and runs without issue. This lets you test and QA the code more thoroughly before merging into your main branch.
+
+::: {.callout-note}
+Chose one method below to create your new branch, which we will call "development". Then follow the instructions at the bottom of this page to update your logbook.
+:::
+
+::: panel-tabset
+## Git Bash
+
+1.  Ensure you're on your own personal main branch that you created in [making a branch](#making-a-branch). If you aren't sure use:
+
+``` bash
+git checkout -b <github_username>/main
+```
+
+2.  Pull the latest changes from the remote repository.
+
+``` bash
+git pull origin <github_username>/main
+```
+
+3.  Create your new development branch
+
+``` bash
+git checkout -b <github_username>/development
+```
+
+4.  Push the new branch to the remote repository:
+
+``` bash
+git push -u origin <github_username>/development
+```
+
+5.  Check that the new branch shows in the branch list.
+
+``` bash
+git branch
+```
+
+![Creating a new branch in GitBash](./images/dev_branch_GitBash.png)
+
+## RStudio
+
+1. Ensure you are on your personal main branch.
+
+2. In the Git panel, click the purple new branch symbol ![symbol containing two purple boxes branching from a diamond](images/new-branch_rstudio-button.png) as to the left of the username in the screenshot below.
+
+3. Then enter your development branch name as **`<github_username>/development`** (but replacing <github_id> with your own GitHub username, e.g. `jsmith_development`)
+
+![Creating a new branch in RStudio](./images/dev_branch_RStudio.png)
+
+## GitHub Desktop
+
+1. Click **Branch** in the menu bar and then select **New branch...** as shown in the screenshot below.
+
+2. Then enter your branch name as **`<github_username>/development`** (but replacing <github_id> with your own GitHub username, e.g. `jsmith_main`)
+
+![Creating a new branch in GitHub Desktop](./images/dev_branch_GitHubDesktop.png)
+
+## VS Code
+
+1. The current branch **`(<github_username>main)`** should be listed in the very bottom left hand corner of the VS Code window frame. If you left click on this, you should then see a menu appear at the top of the VS Code window with some branch options (as shown in the screen shot below).
+
+2. Click **+ Create new branch...** and then enter your branch name as **`<github_username>/development`** (but replacing <github_id> with your own GitHub username, e.g. `jsmith_development`).
+
+3. You should now see the branch name listed in the bottom left of the window frame shown as the branch you just created, meaning any changes you currently make will be applied to that new development branch (and not the main branch, or your personal main branch).
+
+
+## PyCharm
+
+1. Open up the Git panel in PyCharm and you should see something like the screenshot below. Right click on your **`<github_username>/main`** branch and select **New branch from '\<github_id\>/main'...**.
+
+2. Then enter your branch name as **`<github_username>/development`** (but replacing <github_id> with your own GitHub username, e.g. `jsmith_development`).
+
+![Creating a new branch in PyCharm](./images/dev_branch_PyCharm.png)
+
+:::
+
+::: callout-tip
+## Edit your git-academy-log file
+Now you have made your development branch, go to your git log and update tick the 'making a development branch' box. Use the [recording changes](recording-changes) section for a reminder on how to make and save changes. Ensure to commit and push your changes.
+:::

git-refresher/recording-changes.qmd

@@ -1,8 +1,8 @@
 ---
-title: "Recording changes (add and commit)"
+title: "Recording changes (add, commit and push)"
 ---
 
-This section will guide you through recording changes you make to your repo through the process of [**adding**](../glossary.html#add) and [**staging**](../glossary.html#stage) files.
+This section will guide you through recording changes you make to your repo through the process of [**adding**](../glossary.html#add), [**staging**](../glossary.html#stage) and [**pushing**](../glossary.html#push) files. 
 
 These steps help you manage and track changes in your project, making collaboration and version control efficient and reliable.
 
@@ -38,6 +38,10 @@ Having [created your own branch](making-a-branch.html), follow the instructions
 -   Commit changes with a message by entering:
 
     `git commit -m "Checked clone sandbox and make new branch tasks"`
+
+- Push the changes to the remote repository 
+       `git push origin <github_username>/main`
+
 
 ## RStudio
 
@@ -54,6 +58,8 @@ Having [created your own branch](making-a-branch.html), follow the instructions
 
 Note that you can see the changes made by comparing the green (current version) and the red (old version) highlighted sections.
 
+- Then either push up your changes to the remote directly from the commit box using the green 'push' upwards arrow in the top right corner, or close the box and push using the 'push' green arrow in the Git window. 
+
 ## GitHub Desktop
 
 ## VS Code
@@ -75,4 +81,7 @@ OR
 -   Click "Commit".
 
 ![](images/pycharm_commit_msg.png){fig-alt="Highlighting the commit message section and the Commit button in the Commit pop up window that appears after completeing the last step."}
+
+-   Push the committed changes to the remote repository by clicking the "Push" button in the top-right corner of the PyCharm window.
+
 :::

github-devops-refresher/pull-requests.qmd

@@ -0,0 +1,65 @@
+--- 
+title: "Creating pull requests"
+---
+
+::: callout-information
+You will need two branches to merge to be able to create a pull request. If you haven't already, follow the steps in [making a branch](../git-refresher/making-a-branch.qmd), [recording changes](../git-refresher/recording-changes.qmd) and [create more branches](../git-refresher/making-more-branches.qmd) to be able to create and complete a mock pull request 
+:::
+
+A [pull request](../glossary.html#pull_request)  allows you to notify your team about changes you've committed and pushed to a branch in a repository on GitHub. Once a pull request is opened, you can discuss and review the potential changes with collaborators and add any necessary follow-up commits before the changes are merged into the main branch.
+
+Now you have made changes in your [development branch](making-a-development-branch), we will practice this by merging the changes into your main branch using a pull request.
+
+## Creating pull requests
+
+Once you have made all the changes you want to include in this batch of work, you'll bundle all of your commits together into a pull request for review.
+
+::: {.callout-note}
+Before attempting to create your pull request, make sure to have pushed any changes on the branches involved to the remote repo on GitHub
+:::
+
+::: panel-tabset
+## Git Bash
+
+Create your pull request, adding a title and a description of your changes 
+
+``` bash
+gh pr create --base <github_id>/main --head <github_id>/development --title "Update to log book" --body "Updating logbook to reflect completing the development branch task."
+```
+
+## GitHub Website
+
+1. Go to the [git-academy-sandbox](https://github.com/dfe-analytical-services/git-academy-sandbox) repository page on GitHub.
+
+2. Navigate to the Pull requests tab underneath the repository title. 
+![](images/pull_requests_tab.png){fig-alt="Higlighting the Pull requests tab on GitHub."}
+
+3. Open a pull request by clicking the "New pull request" button.
+
+4. Ensure the base branch is set to your own main branch (<github_username>/main)  and the compare branch is set to your development branch (<github_username>/development).
+
+![](images/pull_request_branch_selection.png){fig-alt="Higlighting where to change the base and compare branches once you have pressed the 'create a pull request' button on GitHub."}
+
+
+5. Create Pull Request: Click the "Create pull request" button. Add a title and description for your pull request. You may wish to explain what changes and been made, and why. 
+
+6. You don't need to add any reviewers in this training, but please do take a moment to notice where you can add team mates to review your pull requests in your own work to the right of the description. Any reviewers you add will be notified by email that there is a pull request for them to review.
+
+7. Once you are happy with your title and description, click 'Create pull request' to confirm. 
+
+8. You will then want to check whether there are any merge conflicts. If there are merge conflicts, they will need resolving before you are able to complete your pull request. 
+
+## GitHub Desktop
+
+1. Ensure you are on the development branch. 
+
+2. Click on the 'Branch' menu and 'Create pull request' 
+
+3. Click 'open in browser'. This will open GitHub in your web browser with the pull request form pre-filled. 
+
+4. Add a title and description for you pull request and then click 'Create pull request' 
+
+## VS Code 
+
+## PyCharm 
+::: 

github-devops-refresher/reviewing-pull-requests.qmd

@@ -0,0 +1,31 @@
+---
+title: "Reviewing pull requests"
+format: html
+---
+
+When a pull request is created, it's important to review the changes carefully. This process helps ensure that the code meets the project's standards and doesn't introduce any new issues. During the review, you can discuss the changes with the author, suggest improvements, and request additional commits if necessary.
+
+We will practice this by reviewing the pull request you have just made in [creating pull requests](pull-requests.qmd).
+
+### GitHub Website
+
+1. Go back to the [git-academy-sandbox](https://github.com/dfe-analytical-services/git-academy-sandbox) repository overview page on GitHub, as if you have just come to find the pull request your colleague has asked you to review. 
+
+2. Navigate to the 'Pull requests' tab. 
+
+3. Click on the pull request you want to review, in this case the one you created above. 
+
+![](images/pull-request-in-GitHub.png){fig-alt="Higlighting where open pull requests show in GitHub once the Pull request tab has been opened."}
+
+4. Review the changes by looking at the "Files changed" tab. You can see a side-by-side comparison of the changes made. Add comments by clicking the "+" icon next to the lines of code you want to comment on.
+
+![](images/pull-request-files-changed.png){fig-alt="Higlighting where to view comparison of changes made and make comments on a pull request."}
+
+5. When reviewing pull requests, you may also wish to view changes locally to check the code runs and view any outputs.You can do this by pulling and changing to the branch that is being requested to be merged in.   
+
+6. Once you have reviewed the changes, you can leave general feedback, approve or request changes by clicking the 'review changes' button.
+
+![](images/pull-request-review.png){fig-alt="Higlighting where to provide general feedback, request changes or approve on a pull request."}
+
+7. Once you are happy with the changes, you should approve the pull request. The person who created the request will then get an email letting them know their changes have been approved. It can also be helpful to send them a direct message to let them know you have reviewed their PR! They can then go back and complete the request.  
+

glossary.qmd

@@ -20,9 +20,21 @@ Committing is where you record changes in the Git history. This is one of the mo
 
 Cloning a repository is the process of creating a copy of a repository folder system on your local working environment (e.g. your laptop computer).
 
+## Pull
+
+Performing a "pull" updates your current local working branch with any changes from the remote branch. If you're working with other people on a project, you should pull every day that you interact with a repository, at the minimum.
+
+## Pull request 
+
+A pull request is a method used in Git to propose changes to a branch. It allows collaborators to review and discuss changes before merging into the main branch. 
+
+## Push
+
+Pushing is the process of updating the remote branch with local commits. 
+
 ## Repository
 
-A repository (or repo) is effectively a project folder. A given repostory would usually contain all the work for a specific project (e.g. a data pipeline, an R-Shiny app, etc).
+A repository (or repo) is effectively a project folder. A given repository would usually contain all the work for a specific project (e.g. a data pipeline, an R-Shiny app, etc).
 
 ## Stage
 

pre-requisites.qmd → prerequisites.qmd

@@ -1,5 +1,5 @@
 ---
-title: "Pre-requisities"
+title: "Prerequisites"
 ---
 
 ## Git