Merge pull request #2 from nsccs/github-workshop

GitHub Workshop

README.md

@@ -30,4 +30,5 @@ Read [Creating a Book](https://rust-lang.github.io/mdBook/guide/creating.html#cr
 ```
 
 Look at existing Chapters for further examples.
+Hosted at [https://nsccs.github.io/](https://nsccs.github.io/)
 

src/SUMMARY.md

@@ -2,6 +2,7 @@
 
 - [Workbook](introduction.md)
 - [Git and GitHub Workshop](git_and_github_workshop/README.md)
-  - [Get Started](git_and_github_workshop/git_started.md)
-  - [Basic Commands](git_and_github_workshop/basic_commands.md)
-  - [Open Source](git_and_github_workshop/open_source.md)
+  - [Git Started](git_and_github_workshop/git_started.md)
+  - [Git Basics](git_and_github_workshop/git_basics.md)
+  - [GitHub Basics](git_and_github_workshop/github_basics.md)
+  - [Contribute](git_and_github_workshop/contribute.md)

src/git_and_github_workshop/README.md

@@ -0,0 +1,13 @@
+## Git and GitHub Workshop
+
+### Purpose
+
+This is a crash course in Git and GitHub with the intent on providing enough information so that a student may begin to use Git for their personal projects and more importantly to begin to collaborate with others. This will just touch the surface and will not go into detail about troubleshooting. When issues arise, and they will, we hope the that the club can be a helpful resource to help troubleshoot along with the usual internet sources.
+
+### Git
+
+The most used distributed version control system in use today. Git tracks changes in files and allows for multiple people to work on the same codebase.
+
+### GitHub
+
+A platform and cloud-based service for software development that uses Git. GitHub offers feature rich free accounts and currently students qualify for Pro accounts. The platform is a great way to get started with version control and to begin to collaborate with your fellow students.

src/git_and_github_workshop/contribute.md

@@ -0,0 +1,37 @@
+# Contribute to Other Projects
+
+### Put it all together
+
+This has all been a lead up to contributing to projects that are hosted in the NSCCS organization. With just a few more steps you will be able to contribute to this and any other public repository on GitHub.
+
+### Keywords
+
+fork - Copy of a repository that exists in your GitHub space
+upstream - points to the original repository that you forked
+
+### Contribute to a Repository on GitHub
+
+The last concept for this workshop is called a Fork. A fork of a repository is a copy of that repository in your own GitHub space.
+
+To make a contribution to the original project you first fork the original repository. We will use [this one](https://github.com/nsccs/ForkPracticeCareerPrep).
+
+Then configure the upstream remote
+
+```shell
+git remote add upstream https://github.com/nsccs/ForkPracticeCareerPrep.git
+# Then verify
+git remote -v
+```
+
+The rest is what was previously covered:
+
+- Clone your copied (forked) repository to your local computer
+- Create a feature branch to do your work
+- Create PR of your complete work from your feature branch into the upstream branch
+- Anxiously await feedback
+
+![Fork Example](img/fork-example.png)
+
+You have just made your first contribution to an open source repository!
+
+Check the club [organization](https://github.com/nsccs) for ongoing projects that you might want to get involved with. If you have ideas please list them on Discord and invite people to contribute.

src/git_and_github_workshop/git_basics.md

@@ -0,0 +1,47 @@
+# Git Basics
+
+### Keywords
+
+- stage         - add a file to be committed
+- commit        - The state of the repository at this point in time is saved
+- checkout      - Refers to the creation or switching between branches or commits.
+
+### Concepts
+
+Git is a version control system that allows one or more people to manage different versions of a repository. A repository can be though of as a project directory. A repository contains documents like text, code, and configuration files as well as images. The repository, often referred to as a "repo", also contains the change history called a commit history. Each commit is a saved version of the repo at that point in time. You can think of a commit history as a series of backups.
+
+**Basic Commit History**
+
+![Git Commit History](img/basic-commit-history.png)
+
+### Create A Local Repository and Make a Commit
+
+1. Mac/Linux open a terminal
+2. Windows open _Git Bash_
+3. Create directory
+4. Navigate through the terminal to the root of the directory 
+5. Type ```git init```
+6. Create a file called _first-markdown.md_ and open it in your favorite text editor/IDE 
+7. Write something in the file and save it 
+8. In the terminal type
+   1. ```git status```
+   2. ```git add first-markdown.md```
+   3. ```git status```
+   4. ```git commit -m "Some message here about what you did."```
+   5. ```git log```
+   6. Repeat these steps. On each iteration attempt to new files, edit existing files, and/or delete files
+
+TODO do a revert
+
+
+### Basic Commands
+
+```shell
+git init                        Creates a new git repository
+git status                      Show status of staged/unstaged files
+git diff                        See changes to the file compared to most recent commit
+git add <file_name>             Add file to commit (stage it)           
+git commit -m "<message>"       Commit files with clear message about commit
+git log                         Display a list of commits
+git revert <commit id>          Revert the commit with provided id
+```

src/git_and_github_workshop/git_started.md

@@ -0,0 +1,31 @@
+# Git Started
+
+### Install Git
+
+#### MacOS
+
+Install [Homebrew](https://brew.sh/)
+
+```shell
+brew install git
+```
+
+#### Windows
+
+[Git for Windows](https://gitforwindows.org/)
+
+#### Linux
+
+Install with the distribution's package manager.
+
+### Configure the CLI
+
+_Prerequisites_
+
+- GitHub username
+- GitHub email
+
+```shell
+git config --global user.name <username>
+git config --global user.email <email>
+```

src/git_and_github_workshop/github_basics.md

@@ -0,0 +1,97 @@
+# GitHub Basics
+
+### Keywords
+
+- clone - Copy a repository from GitHub to your local machine
+- branch - A version of the code that deviates from the branch it originated from
+- Pull Request - A request to merge one branch into another
+- conflict - When git cannot resolve a merge without manual intervention
+
+### Concepts
+
+GitHub is a place to store repositories, share them with other GitHub users, and collaborate with others on projects. GitHub involves the Git installed on your computer to host a _local_ version of the repository on your computer. When you have committed changes you will _push_ your commit history (think upload) to the GitHub platform.
+
+**Multiple Branch Git History**
+
+![GitHub Branching](img/github_branch_example.png)
+
+### Create a Repository on GitHub and Push a Commit
+
+Login to GitHub then create a new repository
+
+![GitHub New Repository](img/github-new-repo.png)
+
+and give it a name, or use the suggested name, then select the option to add a _README.md_. After the repository has been created navigate to the drop-down seen below
+
+![GitHub Clone Dropdown](img/github-clone-example.png)
+
+Copy the link to the clipboard and return to a terminal and type
+
+```shell
+git clone https://github.com/username/repository
+```
+
+A new repository now exists. Change directories into the new repository and open it in your text editor/IDE of choice.
+
+Now the same commands used for Git that were covered previously may be used to track changes within this repository. However, it is time to introduce the concept of a branch.
+
+```shell
+git checkout -b new-feature
+```
+
+As long as you don't change anything on this branch you can switch back to the main branch with
+
+```shell
+git checkout main
+```
+
+then switch back
+
+```shell
+git checkout new-feature
+```
+
+However, once changes are made within your new-feature branch you may not switch to other branches without first committing those changes.
+
+Make some changes to your readme and commit them. Now to upload these changes to the remote repository you will _push_ the changes with the git command line tool.
+
+```shell
+git push origin new-feature
+```
+
+You have successfully uploaded your code and commit history to the remote repository!
+
+### The Pull Request
+
+The last piece of the puzzle is the _Pull Request_. Could you have done the above steps directly on the main branch? Yup, but it is generally frowned upon and most repositories you will encounter in the wild will have restrictions that do not allow directly pushing to main. 
+
+A _Pull Request_ is an intermediary step that allows you and the people you collaborate with a chance to review your work, test it, and offer constructive feedback. Changes might be requested before the new feature can be merged into the main codebase. There are other actions that can be configured at this stage that are out of scope for this workshop.
+
+Navigate back to your remote repository in the browser and select the _Pull requests_ option from the tabs that start at the left.
+
+![GitHub Tab Menu](img/tab-menu.png)
+
+Press the big green button that says _New pull request_ and you will be presented with two dropdown menus. On the left is the branch you want to merge your work into and the right is your feature branch.
+
+Select _main_ on the left dropdown and _new-feature_ on the right. Then click the green button to create the pull request.
+
+### Basic Git Commands Used with GitHub
+
+```shell
+git checkout -b <new-branch-name>        Create a new branch
+git checkout <existing-branch-name>      Switch to an existing branch
+git add <file_name>                      Add file to commit (stage it)           
+git commit -m "<message>"                Commit files with clear message about commit
+git push <remote> <branch>               Push locally saved commits to a remote
+git pull <remote> <branch>               Pull latest state of repository for selected branch
+```
+
+### Conflicts
+
+The above layout describes scenarios where everything goes well. There are often scenarios where this does not occur. One of the most common issues that arises is when more than one person work on a single document. Person A and Person B create their own new branches off of the _main_ branch. Both Person A and Person B will work with Document C. Person A finishes their work and submits a PR which is approved and merged into _main_.  Then Person B does the same. At this point Document C in _main_ has been changed since Person B originally created their branch. Person B's PR will have a _conflict,_ and it will need to be resolved manually.
+
+**Merge Conflict Git History**
+
+![Merge Conflict](img/merge-conflict.png)
+
+There are various ways to solve merge conflicts within GitHub's platform as well as locally. Reach out for help, search the web, and don't panic!

src/introduction.md

@@ -2,7 +2,7 @@
 
 This book is a collection of workshops and presentations that are hosted by the North Seattle College Computer Science Club. Each chapter represents a separate workshop or presentation.
 
-If you discover any typos or broken links please open a bug ticket, email the club, or better yet create a PR! Your contributions to the club are greatly appreciated.
+If you discover any typos, out of date images, or broken links please open a [bug ticket](https://github.com/nsccs/nsccs.github.io/issues) or email the club. Pull Requests are accepted by anyone from the club so if you do log the ticket feel free to assign it to yourself and make the correction. Your contributions to the club are greatly appreciated!
 
 If you have an idea for a workshop please reach out to leadership on the Discord channel.