Working in GitHub

Digital Etiquette Expectations

This GitHub repository is PUBLIC. Therefore, it is important that you maintain a professional, scholarly persona in this digital space. Thus, civil behavior is required from each of you and appropriate citations are required when referencing source materials, particularly outside of the specified readings listed here.

Since we are working in a collaborative digital space please be careful not to delete or edit other student's work. Just as in the classroom, it is important that we maintain mutual consideration and respect for each other. Note: GitHub provides detailed edit logs (see examples: this page's history or the repository's commit history) that will allow us to revert to earlier versions in the case of accidental deletions; please contact me via email - rparker3 (at) luc (dot) edu ASAP if this occurs.

Because every student is added as a direct collaborator of this repository you all have the ability to delete/change any part of this repository including these wiki pages; therefore, it is extremely important that you are navigating this space in a careful manner so as to not delete or change any of my instructions, lessons, or exercises.

Course Workflow

In the first week of class, we will add each of you as collaborators on this repository. Please note that you will be removed as collaborators at the end of the semester to prevent accidental editing; however, your time as a collaborator on this project will forever exist in this repository's history and the repository will remain public. We have structured this course so students interacting with the course materials and exercises can visit the repository merely as a course website/resource or commit to engaging in our social encoding community.

To download a file, navigate to the file on GitHub and on the right side near the top of the file's content click the button that gives you the "Raw" view of the file. From there you can copy and paste or right click and save.

Using our Issues Board

The issues board is where we expect the most interaction between learners. The board hosts our specific discussion threads for take-home and in-class exercises. It is also a place for learners to come with assignment questions and to request course and project assistance. Think of this space as a community bulletin board.

1. When creating a new issue be sure to assign the issue a label from our list of labels. Labels help us keep the issues board organized.
2. Like most social media sites, GitHub allows you to mention and notify someone by placing the @ symbol before the users handle.
3. Because we are hosting discussions and community interactions on GitHub you should take note that your responses can be "marked up" using GitHub's markdown syntax. In addition to text styling (like bold, italics, and offsetting quoted text) made available via markdown, you are also able to attach files (images are particularly welcome) and insert emojis anywhere on the interface where commenting is available. Please use the GitHub Help Tutorial on basic writing and formatting syntax along with the emoji cheat sheet to assist in writing an engaged response.

While it may seem more convenient to respond to issue-board postings via email when you are notified of new updates, we ask that you select the option to view on GitHub and reply on the interface instead of within your email. Our reason for this request is because replies via email copy the text of the email in your response on the issues-board. This adds unnecessary bloat to our discussion threads and is aesthetically unpleasant. We ask that if out of convenience or desire to respond quickly you do respond via email you return by our next class period to revise your reply and remove the excess email text. You can edit your reply by clicking on the three-dot icon on the top-right corner of your comment and selecting the edit option. Going forward I will add the peaking eyes (:eyes:) emoji to replies that need advised.

Uploading to the SANDBOX

Learners can contribute content to this repository beyond creating engaged issues-board discussions by uploading directly on the Github interface or by using Git at the command line on your computer. While uploading directly thru GitHub is convenient, contributing content in this way is limiting for the uploader compared to the options that become available when a learner is willing to commit a bit further.

Uploading directly on GitHub

Creating a new file directly on GitHub

1. On GitHub, navigate to the main page of the repository.

2. In your repository, browse to the folder where you want to create a file.

3. Above the file list, click "Create new file".

4. In the file name field, type the file name (avoiding spaces, periods, and special characters) immediately followed by the file extension (.txt for plain text, .md for markdown, or .xml for XML and TEI XML.) To create subdirectories, type the / directory separator. We ask learners to include your Loyola usernames in your filenames. This will assist the instructors during grading.

5. On the "Edit new file tab", add content to the file.

6. To review the new content, click "Preview".

7. At the bottom of the page, type a short, meaningful commit message that describes the change you made to the file.

8. Below the commit message fields, the default is to add your commit to the current branch. If you're not on the current branch (master), you should select the master branch. Please note you will have had to complete the steps of emailing me, at rparker3 (at) luc (dot) edu, verifying your email and then accepting a collaborator invitation to upload directly in the master branch. If you have not completed these steps you will be brought through a process called a pull request (see examples here) and your file will not be available until someone else in the class who has accepted their collaborator role merges your request.

9. Commit your file to the repository by clicking "Propose new file".

Adding an existing file directly on GitHub

1. On GitHub, navigate to the main page of the repository.
2. In your repository, browse to the folder where you want to create a file.
3. Above the file list, click "Upload files".
4. Drag and drop the file or folder you'd like to upload to your repository onto the file tree. While learners are permitted to upload any file type the interface allows, we encourage learners to contribute content in plain text, markdown, or markup. Word documents and pdfs prove to be cumbersome when it comes to later incorporating markdown and markup.
5. At the bottom of the page, type a short, meaningful commit message.
6. Below the commit message fields, the default is to add your commit to the current branch. If you're not on the current branch (master), you should select the master branch. Please note you will have had to complete the steps of emailing me, at rparker3 (at) luc (dot) edu, verifying your email and then accepting a collaborator invitation to upload directly in the master branch. If you have not completed these steps you will be brought through a process called a pull request (see examples here) and your file will not be available until someone else in the class who has accepted their collaborator role merges your request.
7. Click "Commit changes".

Uploading with Git at Command Line

Set Up Git

1. Downloading Git Shell: Git is available for download on all three of these platforms: Linux, Mac, and Windows. To download Git on your local machine follow the instructions available on git-scm.com. Since platform downloads differ we are not going to go through a step-by-step installation process. Please note our suggested settings for a Windows installation are as follows: When the download asks about Adjusting your PATH environment, we recommend selecting Use Git Bash only as it provides an unmodified PATH. If the download asks about Configuring the line ending conversations, we recommend choosing the option to Checkout Windows-style, commit Unix-style line endings. For ALL other settings choose the default selection. Once the installation is complete you will be asked if you want a desktop shortcut for Git Bash; make sure the box to create this shortcut is checked.
2. Navigating Git: On a Windows installation you will be using the Git Bash command shell and on a Mac installation, you will be using Terminal. The key to working with Git is always knowing where to find your files in the Finder (on Mac) / File Explorer (on Windows) and in the Terminal/Git Bash Shell. So you need to save in a place where you can easily see your files. In your Finder/File Explorer, make yourself a GitHub directory that lives inside Documents (or on your desktop if that is a more logical place for you). Inside the GitHub directory, you will clone each of your project repositories. In the Terminal/Git Bash Shell, you can navigate to your GitHub directory from the computer's root by typing: cd Documents/GitHub/ if stored in documents or cd Desktop/GitHub/ if stored on your desktop cd means "change directories" and in the above command you are stepping down into Documents (or Desktop) and into the GitHub folder. Use ls to list out the contents of the directory you have stepped down into.
3. Configuring Git: When you first use your command shell you will need to configure Git to recognize your local computer as a correspondent to your remote GitHub account. Use the following commands to configure your local Git installation (these commands can be done in Terminal/Git Bash Shell without needing to specify a directory):
   git config --global user.name "YOUR NAME"
git config --global user.email "YOUR EMAIL ADDRESS"
   Be sure to use the same email address you used when signing up for your GitHub account. This will add your name and email to a file named .gitconfig in your home directory. To verify that you entered your information correctly use the command:
   git config --list.
4. Cloning our Repo: You only have to clone a project once, when you first begin to work on it. Cloning is the copying of a project already in existence on the GitHub server to your local computer so that you can begin to work on it. To clone a repo you use one easy command: git clone. After git clone, you copy the URL of the repo you wish to clone. In terminal/git bash navigate to your main GitHub folder using cd. Then type the following:
   git clone https://github.com/RJP43/LiliElbe_EngagedLearners.git
   Now if you use the command ls you should see a new folder called "LiliElbe_EngagedLearners"

Committing via Command Line
Please see our detailed walk-through here - Git_BasicCommands.md

1. Open terminal / command line shell
2. Navigate to repo.
3. git pull
4. Make changes.
5. git status -- list of changes should be red
6. git add -A OR git add .
7. git status -- list of changes should be green
8. git commit -m "message here"
9. git push