Polishing GH branch chapter

foundations/github/git-branches.md

@@ -1,3 +1,9 @@
+```{image} ../../images/Git-Logo-2Color.png
+:alt: Git Logo
+:width: 600px
+:align: center
+```
+
 # Git Branches
 
 The best practices for a simple workflow for suggesting changes to a GitHub repository are: create your own fork of the repository, make a branch from your fork where your changes are made, and then suggest these changes move to the upstream repository with a pull request. This section of the GitHub chapter assumes you have read the prior GitHub sections, are at least somewhat familiar with git commands and the vocabulary ("cloning," "forking," "merging," "pull request" etc), and that you have already created your own fork of the [GitHub Sandbox Repository](https://github.com/ProjectPythia/github-sandbox) hosted by Project Pythia. That fork is where you will make your first Git branch while following along with this chapter.
@@ -14,9 +20,14 @@ The best practices for a simple workflow for suggesting changes to a GitHub repo
 
 ## Prerequisites
 
-| Concepts              | Importance | Notes |
-| --------------------- | ---------- | ----- |
-| Prior GitHub Sections | Necessary  |       |
+| Concepts                                                   | Importance  | Notes                        |
+| ---------------------------------------------------------- | ----------- | ---------------------------- |
+| [What is GitHub?](what-is-github)                          | Necessary   | GitHub user account required |
+| [GitHub Repositories](github-repos)                        | Necessary   |                              |
+| [Issues and Discussions](github-issues)                    | Recommended |                              |
+| [Cloning and Forking a Repository](github-cloning-forking) | Necessary   |                              |
+| [Advanced GitHub Setup](github-setup-advanced)             | Recommended |                              |
+| [Basic Version Control with Git](basic-git)                | Necessary   |                              |
 
 - **Time to learn**: 30 minutes
 
@@ -26,9 +37,14 @@ The best practices for a simple workflow for suggesting changes to a GitHub repo
 
 Git branches allow for non-linear or differing revision histories of a repository. At a point in time, you can split your repository into multiple development paths (branches) where you can make different commits in each, typically with the ultimate intention of merging these branches and development changes together at a later time.
 
-Branching is one of git's methods for helping with collaborative document editing, much like "change tracking" in Google Docs or Microsoft Word. It enables multiple people to edit copies of the same document content, while reducing or managing edit collisions, and with the ultimate aim of merging everyones changes together later. It also allows the same person to edit multiple copies of the same document, but with different intentions. Some reasons for wanting to split your repository into multiple paths (i.e. branches) is to experiment with different methods of solving a problem (before deciding which method will ultimately be merged) and to work on different problems within the same codebase (without confusing which code changes are relevant to which problem). There are also some convenience bots on GitHub that, if installed in the repository, may not act as intended if your work is all on the `main` branch.
+Branching is one of git's methods for helping with collaborative document editing, much like "change tracking" in Google Docs or Microsoft Word. It enables multiple people to edit copies of the same document content, while reducing or managing edit collisions, and with the ultimate aim of merging everyone's changes together later. It also allows the same person to edit multiple copies of the same document, but with different intentions. Some reasons for wanting to split your repository into multiple paths (i.e. branches) is to experiment with different methods of solving a problem (before deciding which method will ultimately be merged) and to work on different problems within the same codebase (without confusing which code changes are relevant to which problem).
+
+These branches can live on your computer (local) or on GitHub (remote). They are brought together through Git _pushes_, _pulls_, _merges_, and _pull requests_. _Pushing_ is how you transfer changes from your local repository to a remote repository. _Pulling_ is how you fetch upstream changes into your branch. _Merging_ is how you piece the forked history back together again. And _Pull Requests_ are how you suggest the changes you've made on your branch to the upstream codebase.
 
-These branches can live on your computer (local) or on GitHub (remote). They are brought together through Git _pushes_, _pulls_, and _pull requests_. _Pushing_ is how you transfer changes from your local repository to a remote repository. _Pulling_ is how you fetch upstream changes into your branch. And _Pull Requests_ are how you suggest the changes you've made on your branch to the upstream codebase.
+```{admonition} Pull Requests
+:class: info
+We will cover [Pull Requests]((github-pull-request)) more in-depthly in the next section.
+```
 
 One rule of thumb is for each development feature to have its own development branch until that feature is ready to be added to the upstream (remote) codebase. This allows you to compartmentalize your pull requests so that smaller working changes can be merged upstream independently of one another. For example, you might have a complete or near-complete feature on its own branch with an open pull request awaiting review. While you wait for feedback from the team before merging it, you can still work on a second feature on a second branch without affecting your first feature's pull request. **We encourage you to always do your work in a designated branch.**
 
@@ -172,71 +188,34 @@ The above flowchart demonstrates adding commits locally (C3 and C4) before pushi
 
 ## Merging Branches
 
-At this point, we will demonstrate how to merge branches via a Pull Request. Merging is how you bring your split branches of a repository back together again.
-
-![PR](../../images/PR.png)
-The above flowchart demonstrates a simple Pull Request (PR1), the upstream main repository has accepted the changes from the Feature 2 branch of your fork. The latest commit to the Upstream Main repository is now C4. Your Feature2 branch can now be safely deleted. This flowchart has simplified out the remote and local versions of the Feature2 branch.
-
-The demonstration will move from your local terminal to GitHub. Go to your fork of the [GitHub Sandbox Repository](https://github.com/ProjectPythia/github-sandbox). One fast way to get to your fork, is to click the "fork" button and then follow the link underneath the message, "You've already forked github-sandbox."
-
-When you've navigated to your fork, you should see a message box alerting you that your branch `newbranch` had recent changes with the option to generate an open pull request. This pull request would take the changes from your `newbranch` branch and suggest them for the original upstream ProjectPythia github-sandbox repository. You'll also notice that you are on branch `main`, but that there are now 2 branches.
-
-![GitHub](../../images/8-github.png)
-
-If you click on the branch `main` you'll see the list of these branches.
-
-![GitHub Branches](../../images/9-github-seebranches.png)
-
-There you can click on the branch `newbranch` to switch branches.
-
-![New Branch](../../images/10-github-newbranch.png)
-
-Here you will see the message, "This branch is 1 commit ahead of ProjectPythia:main." Next to this message you'll see either the option to "Contribute" (which opens a pull request) or "Fetch Upstream" (which pulls in changes from the original repository). And just above your files you'll see your most recent commit.
-
-Click on the "Open a Pull Request" button under the "Contribute" drop-down.
-
-![Contribute](../../images/11-newbranch-contribute.png)
+Merging is how you bring your split branches of a repository back together again.
 
-This will send you to a new page. Notice that you are now in "ProjectPythia/github-sandbox" and not your fork.
+If you want to merge two _local_ branches together, the steps are as follows:
 
-![Compare](../../images/12-compare.png)
+Let's assume your two branches are named `branchA` and `branchB`, and you want your changes from `branchB` to now be reflected in `branchA`
 
-The page will have the two branches you are comparing with an arrow indicating which branch is to be merged into which. Here, `base` is the upstream origin and `head` is your forked repository. If you wanted, you could click on these branches to switch the merge configuration. Underneath that you'll see a green message, "Able to merge. These branches can be automatically merged." This message means that there are no conflicts. We will discuss conflicts in a later chapter.
+1. First checkout the branch you want to merge INTO:
 
-In a one-commit pull request, the pull request title defaults to your commit message. You can change this if you'd like. There is also a space to add a commit message. This is your opportunity to explain your changes to the owners of the upstream repository.
-
-![Message](../../images/13-message.png)
-
-And if you scroll down, you'll see a summary of this pull request with every commit and changed file listed.
-
-![Summary](../../images/14-prsummary.png)
-
-Click the arrow next to "Create Pull Request" to change this to a draft pull request.
-
-![To Draft](../../images/15-todraft.png)
-
-Once you've clicked "Draft Pull Request," you will be directed to the page of your new pull request. Here you can add more comments or request reviews.
-
-![Draft PR](../../images/16-draft.png)
-
-Clicking "Files Changed" allows you to see all of the changes that would be merged with this pull request.
-
-![Files](../../images/17-fileschanged.png)
-
-If you are working in a repository that has automatic checks, it is a good idea to wait for these checks to pass successfully before you request reviewers or change to a non-draft pull request. Do this by clicking "Ready for Review."
+```
+git checkout branchA
+```
 
-![Review](../../images/18-review.png)
+2. Then execute a `merge`:
 
-When working on a project with a larger team, do NOT merge your pull request before you have the approval of your teammates. Every team has their own requirements and best practice workflows, and will discuss/approve/reject pull requests together. We will cover more about the ways to interact with pull requests through conversations and reviews in a later section.
+```
+git merge branchB
+```
 
-To someone with write permissions on the repository, the ability to merge will look like this green button:
-![Green](../../images/20-green.png)
+A very common way of merging REMOTE branches is via a Pull Request.
 
-However, this pull request will NOT be merged, as the GitHub-Sandbox repository is intended to be static.
+![PR](../../images/PR.png)
+The above flowchart demonstrates a simple Pull Request (PR1), the upstream main repository has accepted the changes from the Feature 2 branch of your fork. The latest commit to the Upstream Main repository is now C4. Your Feature2 branch can now be safely deleted. This flowchart has simplified out the remote and local versions of the Feature2 branch.
 
 ![remotePR](../../images/remotePR.png)
 The above flowchart demonstrates a Pull Request (PR1) without simplifying out the remote vs local versions of the Feature2branch. Typically multiple pushes are made from your local to remote branch before a pull request is drafted to take all of those commits (C3, C4, C6, and C7) into the Upstream Main branch.
 
+We will continue this demonstration and cover the specifics of merging via a [Pull Request](github-pull-request) more thoroughly in the next section.
+
 ## Pulling
 
 Once a team member's pull request has been merged, you will find that these upstream changes are not automatically included in your fork or your branches. In order to include the changes from the upstream main branch, you will need to do a `git pull`.
@@ -298,7 +277,7 @@ git push origin --delete jukent/newbranch
 
 ### What's Next?
 
-Opening a Pull Request on GitHub
+[Opening a Pull Request on GitHub](github-pull-request)
 
 ## References