First lecture restructuring

notes/2023-09-07.md

@@ -5,7 +5,7 @@
 ## Introductions
 
 - Dr. Sarah Brown
-- Please address me as Dr. Brown or Professor Brown, 
+- Please address me as Dr. Brown or Professor Brown  
 
 +++
 
@@ -33,6 +33,20 @@ questions can  be "graded"
 
 
 
++++
+
+
+
+### GitHub
+
+- This class is not a GitHub class
+- GitHub is the main tool that we will be using in this course
+- Not expecting you to be familiar with it
+- Homework is submitted through GitHub in a non-traditional way
+- Great practice for real-life software development with a team or even individual work
+- More on that later
+
+
 +++
 
 
@@ -92,7 +106,8 @@ This information will help me prepare
 
 ## What about AI?
 
-Large Language Models will change what programming looks like, but understanding is always going to be more effective than asking an AI.  Large language models actually do not know anything, they just know what languages loook like and generate text.  
+Large Language Models will change what programming looks like, but understanding is always going to be more effective than asking an AI.  
+Large language models actually do not know anything, they just know what languages loook like and generate text.  
 
 
 *if you cannot tell it when it's wrong, you can not add value for a company*
@@ -119,7 +134,7 @@ Large Language Models will change what programming looks like, but understanding
 - college is not about the facts, but the processes
 
 ```{note}
-We may not think that we use the fact that we know the order of letters in the English language very often. Most of us learned the alphabet with a song, but we do not sing that on a dialy basis. 
+We may not think that we use the fact that we know the order of letters in the English language very often. Most of us learned the alphabet with a song, but we do not sing that on a daily basis. 
 
 However, we do fill out forms where we have to, for example, find the state we live in, in a dropdown and knowing the alphabetical order of the states helps us find ours faster. 
 
@@ -160,25 +175,31 @@ When you know things really well, you apply them without noticing.
 ## Getting started 
 
 
-Your KWL chart is where you will start by tracking what you know now/before we start and what you want to learn about each topic.  Then you will update it throughout the semester. You will also add material to the repository to produce evidence of your learning. 
+Your KWL chart is where you will start by tracking what you know now/before we start and what you want to learn about each topic.  
+Then you will update it throughout the semester. You will also add material to the repository to produce evidence of your learning.  
 
 +++
 
 [Accept the assignment](https://classroom.github.com/a/hiZVsWhI) to create your repo
 
 +++
 1. click on .gihub, then workflows, then track.yml
-2. click the 3 dots menu and select delete
-3. commit directly to main with the default message
-4. back to the main code tab
-5. Click the pencil to edit the readme
-6. Add your name
-7. Add a descriptive commit message
-8. Choose create a branch and open a pull request
-9. name the branch 
-10. Click on the list of commits, now you have one more! 
-
-
+2. pay attention to what commits are currently present (will explain what a commit is in a few minutes)
+3. click the 3 dots menu and select delete
+4. commit directly to main with the default message  
+5. notice that one commit had been added (hmmm, what does this mean?)
+6. back to the main code tab
+7. Click the pencil to edit the readme
+8. Add your name
+9. Add a descriptive commit message
+10. Choose create a branch and open a pull request
+11. name the branch 
+12. Click on the list of commits, now you have one more! 
+
+```{Commits}
+Commits represent a message to your future self/teammates/viewers.  
+They mark what signifigant change has been made between one "checkpoint" in the status of a project and the next
+```
 
 
 
@@ -202,7 +223,7 @@ In your KWL chart, there are a lot of different topics that are not obviously re
 +++
 
 
-We will use learning the tools to understand how computer scientists think and work.
+We will try to understand how computer scientists think and work through learning about the tools they use and some of their history.
 
 
 
@@ -263,10 +284,90 @@ GitHub Docs are really helpful and have screenshots
 
 +++
 
-## Git and GitHub terminology
+# Git and GitHub terminology
+<!--
+I will expand this section of the lecture notes to what I think ought to be included in the introductory lectures.
+I realize that all this information might not fit in the first lecture. I also realize that terms mentioned here are mentioned in more detail in future lectures.
+But working with GitHub might be somewhat of a dive into an abyss of the unknown for some (as it was for me when I took this class first) and that might make it intimidating.
+The terms are explained in future lectures in a technical manner. Where here, I attempt to bring them up in the simplest way possible "toddler terms"
+After the first class, students are required to diploy the reflection workflow. Creating a pr, and being told to assign an instructor as a reviewer to it and commit changes.
+Hopefully the following will serve as a simple intro to what these terms mean to reduce confusion.
+-->
+We also discussed some of the terminology for git. We will also come back to these ideas in greater detail later.
+
+## What is git?
+git is a version control system used among software developers for two main reasons:
+- Keep track of all changes that occur to a project
+- Create checkpoints of the project's history showing different versions of the project with logs that explain the changes between one version and the one before it
+git does all of that by keeping compressed copies of all the tracked files in a project while marking changes that happen on the same file with a "change/commit message" provided by the developer.  
+git is a file system!  
+
+## What is GitHub??
+GitHub is a website that is able to visualize everything that git does and also has git within it giving developers the ability to make changes and even develop complete projects from within it.  
+GitHub has many benifits:
+- Helps developers collaborate with each other on the same project
+- Can be considered as a way to backup the source code for projects and access it from different machines to interact with it or download it
+```
+Two or more developers can have access to the same GitHub "repository" (project) giving them the ability to work on their tasks individually at the same time
+```
+
+## git & GitHub terms
+
+### Reposatory (repo)
+A copy of the whole project. 
+```
+There could be different copies of a repo; online repos that lives on GitHub as well as multiple local copies that can exist on different machines of the developers
+```
+
+A project can exist in multiple places at the same time, although each instance of the project in each place is considered its own version of the project.  
+For example, a project's instance on GitHub is considered to be the online version of the project (online repo), aka mainstream (it is most likely to be considered the mainstream because it will constantly be maintained and updated my the project managers and developers and all other instances will be synced to it).  
+A local instance of the project is most likely to exist on each developer's personal machine.  
+Every instance of the project needs to be frequently synced with the mainstream.  
+Getting an instance synced to new changes that occurred on the mainstream is done by performing a "pull" which is pulling all the changes from mainstream to the local instance.  
+On the other hand, syncing the mainstream with changes that a developer performed on their local repo is done by performing a "push" which is pushing the changes from the local repo to the mainstream.
+
+
+### Branch
+A branch starts off as a copy of the current project but it lives in the same directory (folder). It is just a different state of the same project.  
+Once changes have been done to that branch git realizes that there are differences between the "main" branch and the current branch and provides us with the ability to do whatever we want with these differences (discard them, add them into the main branch in what's called a "merge")  
+```
+A branch is meant to be created to experiment with a particular modification on the project.
+Once the modification is implemented and tested to satisfaction. git provides an easy way to include that modification in the main project files "main branch"
+Developers can each be working on a different part of the project, each on a different branch and then once they’re done they can both contribute their individual changes to the main branch of the project.
+```
+A project's repository normally has a main/master branch that holds the official, release-ready or release-intended version of the project and other branches that are copies of main or of another branch at some point in history, that are used to make contributions, changes or fixes to the code.  
+
+
+```
+A project's repository normally has a main/master branch that holds the official, release-ready or release-intended version of the project
+```
+
+### Commit
+A commit is a checkpoint in the project assossiated with message written by the person who made a change to the repo.  
+That commit is meant to mark an new state in the project while reserving the old state in case we decide to go back to it.  
+git keeps a log of all commits made to the project. with details about who made what the changes were, who made them, when and why.
+
+````{margin}
+```{Benifits}
+Imagine you're working on a large code base and for a few hours and have been testing along the way. But all of a sudden your program fails to run horrifically.
+With git you can use commits and to compare the lines in a code module before and after a commit. Additions, deletions and edits. You can also reverse to a commit where the program was working if worst comes to worse. And then start from that point again. That can be a life saver a lot of times
+```
+````
+
+### Pull Requests
+A pull request (pr) is when a developer had contributed to a project by working on the code in a branch that was made specially for them to work on that change or added feature.  
+Once they're done and they feel comfortable enough that the changes are good enough to be added to the main branch.   
+The developer can create a pr on GitHub to notify other team members especially if there was a lead developer that needs to review, test and approve these changes before accepting the merger to the main branch.
+
+### Merge
+A merge is when the changes from a branch get merged into the main branch or any branch that lives in the repo.  
+Merges can be done without the need of a pr. A pr is just a formal way to add those changes while abiding by the rules of the team that the developer is a member in.
+
+```{note}
+If two branches made different changes to the same line or block of code and are being merged together a merge conflict will occur, that needs to be resolved by a project manager that will look at the two versions of the code, compare them and choose which of them will be kept in the code and which will be discarded.
+```
 
 
-We also discussed some of the terminology for git. We will also come back to these ideas in greater detail later.
 
 +++
 
@@ -342,4 +443,4 @@ When you click that link join the existing team, do not make a new one
 ## Practice 
 
 ```{include} ../_practice/2023-09-07.md
-```
+```