Merge pull request #9 from AdyGCode/dev

Dev

.obsidian/plugins/obsidian-icon-folder/data.json

@@ -6,6 +6,7 @@
     "emojiStyle": "native",
     "iconColor": null,
     "recentlyUsedIcons": [
+      "FasFolder",
       "FasImage"
     ],
     "recentlyUsedIconsSize": 5,
@@ -23,5 +24,7 @@
     "iconsInNotesEnabled": true,
     "iconIdentifier": ":"
   },
-  "assets": "FasImage"
+  "assets": "FasImage",
+  "docs": "FasFolder",
+  "theme": "FasFolder"
 }

.obsidian/workspace.json

@@ -4,16 +4,16 @@
     "type": "split",
     "children": [
       {
-        "id": "24d108f19bd80217",
+        "id": "f854b54e1c2c8592",
         "type": "tabs",
         "children": [
           {
-            "id": "08eecd3350f5b33e",
+            "id": "e74c320159094cdf",
             "type": "leaf",
             "state": {
               "type": "markdown",
               "state": {
-                "file": "docs/14-forking-over-code.md",
+                "file": "docs/18-workflows.md",
                 "mode": "source",
                 "source": false
               }
@@ -85,7 +85,7 @@
             "state": {
               "type": "backlink",
               "state": {
-                "file": "docs/14-forking-over-code.md",
+                "file": "docs/18-workflows.md",
                 "collapseAll": false,
                 "extraContext": false,
                 "sortOrder": "alphabetical",
@@ -102,7 +102,7 @@
             "state": {
               "type": "outgoing-link",
               "state": {
-                "file": "docs/14-forking-over-code.md",
+                "file": "docs/18-workflows.md",
                 "linksCollapsed": false,
                 "unlinkedCollapsed": true
               }
@@ -125,7 +125,7 @@
             "state": {
               "type": "outline",
               "state": {
-                "file": "docs/14-forking-over-code.md"
+                "file": "docs/18-workflows.md"
               }
             }
           }
@@ -147,12 +147,22 @@
       "table-editor-obsidian:Advanced Tables Toolbar": false
     }
   },
-  "active": "08eecd3350f5b33e",
+  "active": "e74c320159094cdf",
   "lastOpenFiles": [
+    "assets/Pasted image 20240314154647.png",
+    "assets/Pasted image 20240314154551.png",
+    "docs/15-diffs.md",
+    "assets/diff-difference.png",
+    "assets/diff-hunk-headers.png",
+    "assets/diff-header.png",
+    "docs/18-workflows.md",
+    "docs/14-forking-over-code.md",
+    "assets/Pull-Request-Practice.md",
+    "assets/collaboration.png",
+    "docs/12-remotely-useful.md",
+    "docs/98-command-line-extras.md",
     "CONTRIBUTE.md",
     "docs/98-command-line-extras.md",
-    "docs/14-forking-over-code.md",
-    "docs/15-workflows.md",
     "assets/pasted-image-20240314105028.png",
     "assets/pasted-image-20240314102512.png",
     "assets/front-cover.svg",
@@ -163,32 +173,22 @@
     "output",
     "docs/00-Back.md.md",
     "docs/00-Front.md.md",
-    "assets/pasted-image-20240216114456.png",
-    "assets/pasted-image-20240216124422.png",
     "docs/99-references-and-resources.md",
     "docs/08-status-add-commit.md",
     "docs/06-read-me.md",
     "ReadMe.md",
     "theme/style.css",
     "theme",
     "docs/13-why-hello-dolly.md",
-    "docs/12-remotely-useful.md",
     "docs/11-merging-and-conflicts.md",
     "docs/10-shaking-the-tree.md",
     "docs/09-git-history.md",
     "docs/07-ignore-me.md",
     "docs/05-global-settings.md",
     "docs/04-git-started.md",
     "docs/02-getting-ready.md",
-    "docs/03-repositories-and-folders.md",
-    "docs/01-what-is-version-control.md",
     "docs",
     "assets/brave_dWSQwZYc3F.mp4",
-    "assets/2024-03-01_15_03_52-AdyGCode_git-remote-demo-ii-Brave.png",
-    "assets/2024-03-01_14_57_49-New-repository-Brave.png",
-    "assets/2024-03-01_14_57_43-New-repository-Brave.png",
-    "assets/2024-03-01_14_57_37-New-repository-Brave.png",
-    "99-references-and-resources.md",
     "themes",
     "ReadMe.md~",
     "02-getting-ready.md~",

ReadMe.md

@@ -32,7 +32,7 @@ This ReadMe does not need a Table of contents, instead we provide links to each
 - [12 Remotely useful](docs/12-remotely-useful.md)
 - [13 Why, Hello Dolly](13-why-hello-dolly.md)
 - [14 Forking over code](docs/14-forking-over-code.md)
-- [15 Workflows](docs/15-workflows.md)
+- [15 Workflows](docs/18-workflows.md)
 - 
 - ...
 - [99 References and Resources](docs/99-references-and-resources.md)

assets/Pull-Request-Practice.md

@@ -0,0 +1,147 @@
+# Intro to PRs
+
+![Illustrative image of people working together](collaboration.png)
+
+You can use the following guide to learn how and why to create a pull request.
+
+## What is a pull request?
+
+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.
+
+<!-- TODO: Add information on PRs and forks. -->
+
+## Set up your environment
+
+### Create a local copy of the repository
+
+Copy the following file to a new Git repo.
+
+```bash
+cd ~/source/repos
+git init my-first-pr
+cd my-first-pr
+cp ~/Downloads/README.md .
+```
+
+**IMPORTANT:** Please ensure you continue working on the file copy and not the original.
+
+### Create an empty repository on GitHub
+
+1. Go to [GitHub](https://github.com) and sign in.
+2. In the upper-right corner of any page, select `➕`, and then select `New repository`.
+3. Name your repository `my-first-pr`.
+   **IMPORTANT:** Do not initialize the repository with a `README`, `.gitignore`, or license.
+4. Note the name of your repository `URL` here: **<URL>**
+   You'll need this information later.
+
+### Add the remote repository
+
+1. In the terminal, add the URL of the repository you created on GitHub as the remote repository.
+
+```bash
+git remote add origin <URL>
+```
+
+2. Check that the remote repository was added.
+
+```bash
+git remote -v
+```
+
+3. Consider why it does not provide a URL for pull, only `push` and `fetch`?
+
+---
+
+4. Push the local repository to the remote repository.
+
+   ```bash
+   git push -u origin main
+   ```
+
+5. Refresh the GitHub page for your repository. You should see this `README.md` file.
+
+### Why are pull requests called "Pull Requests"? (wrong answer)
+
+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.
+
+<!--TODO: This answer is SO wrong, I think we need to fix it! -->
+
+### Create a local branch
+
+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!
+
+You decide to fix the definition above, but BEFORE you do that, you need to create a new branch to work on.
+
+1. Create a new branch and switch to it.
+
+```bash
+# Older style:
+git checkout -b fix/pr-definition
+# Or, newer style:
+git switch -c fix/pr-definition
+```
+
+2. Edit this file and address the two TODO items in two separate commits.
+
+```bash
+git commit -am "Add forks to the PR definition"
+git commit -am "Give correct reason to why PRs are named that"
+```
+
+3. Check on GitHub whether the branch exists there or not. Does it? Why or why not?
+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.
+
+```bash
+git push
+# or in full
+git push origin fix/pr-definition
+```
+
+You probably got a similar error to this:
+
+```text
+fatal: The current branch fix/pr-definition has no upstream branch
+```
+
+5. What does this error mean? Why did it happen? Git explains how to fix it by running a command that will:
+
+   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).
+   2. Set the local branch to track the remote branch.
+   3. Push the local branch to the remote repository.
+
+7. Run the command that Git suggests to fix the error. There is also a shorthand for this command:
+
+```bash
+git push -u origin fix/pr-definition
+```
+
+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?
+
+### Create a pull request
+
+1. Select `Compare & pull request`.
+2. Note that the base repository and compare branch are correct.
+3. Add a title and description for your pull request. Here is an example of a high-quality pull request description:
+
+   ```markdown
+   Title: Fix PR definition
+   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".
+   ```
+
+4. Select `Create pull request`.
+
+### Review and merge a pull request
+
+1. Go to the `Pull requests` tab on the repository page.
+2. Select the pull request you created.
+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.
+4. Add a comment to the pull request. Please feel free to ask for more information, suggest changes, or approve the pull request.
+5. Select `Merge pull request` to merge the changes into the `main` branch.
+
+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`.
+
+### Optional: Fork someone else's repository and create a pull request
+
+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.
+
+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.

docs/14-forking-over-code.md

@@ -44,15 +44,16 @@ In the contribution type of fork, you are using the fork almost like a branch.
 
 The big thing about this is that you only need read permissions to the original repo to start working.
 
-## Forking in the Enterprise
+# Forking in the Enterprise
 
 Remember that forking is a GitHub feature. Other Git hosting solutions may have similar features.
 
 Forking is common practice in open source development.
 
 
-## Comparing Forks v Branches
+# Comparing Forks v Branches
 
+In an article by SSW in their "SSW Rules" they outline some of the fundamental differences:
 
 |                                           | Forks                                                                                  | Branches                                                              |
 | ----------------------------------------- | -------------------------------------------------------------------------------------- | --------------------------------------------------------------------- |
@@ -62,11 +63,11 @@ Forking is common practice in open source development.
 | **Scope of changes**                      | Typically involve significant changes                                                  | Typically involve smaller changes                                     |
 | **Collaboration**                         | Used to develop ideas in isolation from the main team                                  | Used to develop ideas that the main team is working on                |
 
-Based on SSW.Rules "Do you know when to create a fork vs a branch".
+> Based on SSW.Rules "Do you know when to create a fork vs a branch".
+> 
+  SSW.Rules. (n.d.). _Git - Do you know when to create a fork vs a branch?_ [online] Available at: https://www.ssw.com.au/rules/fork-vs-branch/ [Accessed 14 Mar. 2024].
 
-SSW.Rules. (n.d.). _Git - Do you know when to create a fork vs a branch?_ [online] Available at: https://www.ssw.com.au/rules/fork-vs-branch/ [Accessed 14 Mar. 2024].
-
-## How to Fork
+# How to Fork
 
 Forking is done within the GitHub Web GUI.
 
@@ -77,3 +78,74 @@ The basic process is:
 - Fork the repository (to your account)
 - Clone the repository to your local device
 
+
+
+# Pull Requests
+
+A pull request is a GitHub feature (with similar features in other git hosting).
+
+A pull request proposes the target repo pulls from a secondary repo or branch. This is in place of pushing to a target repo (“production”) or merging to a production branch.
+
+Thus “pull request” means:
+> request a pull from your branch instead of pushing to the target repo/branch
+
+### Anatomy of a Pull Request
+
+A pull request has the following features:
+- Has a target repo/branch <=> source repo/branch
+- Has a state: Open, Closed, Merged, Draft
+- Presents a moving Δ between the target and source
+- Contains an area to review and discuss, including in line comments
+- May be a trigger for automated checks and workflows
+
+#### When combined with Protected Branches
+
+GitHub allows you to specify that branches with a given name pattern are protected, this means that the branch may insist on:
+- A pull request before merge,
+- At least X reviewers or particular reviewers before merge is permitted
+- and other limitations on the request.
+
+## How to Make a Pull Request
+
+Imagine you created a fork or branch or both, and you think your changes are good enough for the main branch/repo... What should happen next?
+
+There are two options:
+- Merge and see
+- Propose, discuss/review, then merge
+
+### Merge and See
+
+In “merge and see” your merge your changes and hope for the best. 
+
+This is not as crazy as it sounds since Git is meant to provide us with fail safes... What are the fail safes Git provide you with?
+
+But:
+- You must have permissions to merge into the repo/branch
+- The code may not meet quality standards and organizational requirements
+- These may be “silent but deadly”...
+
+A better option could be...
+
+### Propose, Discuss/Review and Merge
+
+Many people and organizations want to review proposed changes prior to merging. This is because the prospect of "bad code" becoming part of the software is not something anyone looks forward to.
+
+The process of Propose, Review and Merge provides the following advantages:
+- Enhances quality
+	- The process ensures that code that gets “mainlined” has been proofed.
+- Encourages collaboration
+	- Any changes are not just the responsibility of the contributor of the code. 
+	- Reviewers and the owners of the project also have a stake in a change.
+- Improves security
+	- We can have more authors than committers to the project.
+	- These committers act as ‘gatekeepers’ who are the only ones allowed to merge a proposed set of a changes to given repos and branches.
+
+## Exercise
+
+In this repository you will find an exercise that you should download and follow. It is a single Markdown document with all the steps to practice pull requests. Download the [Pull Request Practice Read Me Markdown document](../assets/Pull-Request-Practice.md), and rename it `ReadMe.md`.
+
+Open this file and follow the instructions.
+
+To go with this exercise, there is an image, [collaboration.png](../assets/collaboration.png) to be downloaded and used in the exercise.
+
+[13: Cloning](13-why-hello-dolly.md) | [15: Workflows](18-workflows.md)