Initial commit

.github/commit_content/be_gone_dirty_water.md

@@ -0,0 +1,8 @@
+
+## Be Gone, Dirty Water
+
+One night you again sit down to a dinner of fresh-caught catfish — don't forget to wash your hands in the water bucket after cleaning those stinky fish! And those dirty dishes, just wash them in the bucket, too. Then get rid of that smelly bucket of water —just throw it out in the yard. But your neighbor complains about having to smell rotten fish all night, and you complain to him about the water they wash their dirty clothes in finding its way to your front step. And then there's that hole your neighbor dug for his toilet — well, use your imagination.
+
+It seems that there is something more to life than just getting and using water — you need to get rid of your wastewater. You need to build a "water-return system," commonly known as a sewer network. Again, lay a network of pipes from your homes back downhill. Connect your sinks, baths, and toilets to the pipes to take away unwanted water. Run the pipes back into the creek (downstream from your water-intake pump!) and let the creek carry away your waste water.
+
+You're happy until the Hewlett family downstream starts complaining about your raw sewage flowing in the creek beside their home. You realize you need to send the waste water from your house to some place where you can clean it up before putting it back in the creek. You build a [sewage-treatment plant](https://www.usgs.gov/special-topic/water-science-school/science/wastewater-treatment-water-use-united-states), run pipes from the town's houses to it, and begin treating wastewater before releasing it into Dryville Creek.

.github/commit_content/readme_participant_end.md

@@ -0,0 +1,5 @@
+# USGS Data Science tutorial for Git and GitHub workflow
+
+![congrats](https://user-images.githubusercontent.com/13220910/81443707-86452d80-913b-11ea-9ad4-7be24ff64c39.gif)
+
+Congratulations - you completed the tutorial! This canonical repository will eventually be deleted, but your fork will continue to exist. If you would like this congratulatory page to appear on your fork, pull from upsteam (`git pull upstream main`) and then push to your fork (`git push origin main`).

.github/commit_content/readme_participant_start.md

@@ -0,0 +1,5 @@
+# USGS Data Science tutorial for Git and GitHub workflow
+
+*This repository contains the issues and starting content to teach the DS fork-and-pull style workflow for a specific participant.*
+
+**TO START:** Go to the issues tab and click on issue #1 (the bottom one; they are listed in reverse order). Each issue will tell you what to do to complete it and then give instructions for proceeding. Ignore the labels associated with issues, those are used to assist the underlying automation that guides you through the process.

.github/commit_content/storing_water.md

@@ -0,0 +1,4 @@
+
+## Storing Water for a Rainy Day
+
+You start thinking... a reservoir (you can call it a lake) above town could really serve a lot of purposes. A lake will provide a place for you to have fun — go swimming, boating, catch catfish, and relax. You can run your water-supply intake pipes from the lake instead of from your creek, especially since the flood destroyed your water-intake pumping station. With a dam you can release only the amount of water you want into the creek below the dam, thus making sure you have just the right amount of water running in Dryville Creek at all times. A dam would even help prevent flooding downstream because you can hold extra rainfall and runoff during a storm and slowly release it afterward. You can build a bigger paddle wheel, or, better yet, construct a real hydroelectric power plant in your dam to start generating electricity! More problems solved.

.github/issues_to_create/issue_01.md

@@ -0,0 +1,16 @@
+Scenario: You are pointed to a code repository on GitHub (this one) for a project that you just joined. You need to start contributing to this codebase. Where do you start? 
+
+So far in the GitHub lessons, you've learned about using GitHub for version control to make and save changes (commit) and merge those changes into the code (pull request). You were also taught how to use branches to keep your code separate from the canonical codebase. However, that is not the only workflow that can be followed when using Git and GitHub. In our group, we use a slightly different version in order to manage collaborative development. Below is a generic depiction of our version control workflow. It is known more widely as the "fork-and-pull workflow".
+
+![image](https://user-images.githubusercontent.com/13220910/81212295-4bf05a80-8f9a-11ea-8302-99a231f61480.png)
+
+There is a main version of the code that people are collaboratively developing. Each contributor has their own version of this code online and locally. Changes are made locally, sent to their online version, and then combined with the collaborative version of the code. Contributors are able to get the changes from other users by syncing their local version with the collaborative version of the code. Now let's look at that workflow using Git + GitHub terminology.
+
+![image](https://user-images.githubusercontent.com/13220910/155410782-77ba4334-9253-4e1e-a5f0-ac779569fc6d.png)
+
+There is a main version of the code that people are collaboratively developing (`upstream repository`). Each contributor has their own version of this code online (`forked repository`) and locally (`cloned repository`). Changes are saved locally (`commit`), sent to their online version (`pushed to their fork`), and then combined with the collaborative version of the code (`merged with a pull request`). Contributors are able to get the changes from other users by syncing their local version with the collaborative version of the code (`pull the upstream repository`).
+
+We are going to walk through each of these steps within the workflow in this lesson. We will also learn about merge conflicts and what a `.gitignore` file is all about. 
+
+----
+**Action:** Close this issue after you read about the workflow and proceed to the next issue in sequential order.

.github/issues_to_create/issue_02.md

@@ -0,0 +1,14 @@
+The first step in our workflow when working on a new project is to fork the canonical repository. This creates a copy of the repository that is specific to your user on GitHub. Everyone that is working on the project has their own fork of the repository where they can safely make changes without impacting the main code or other contributor's code.
+
+----
+**Action:** Fork this repo!
+
+1. Open the main repository page, `https://github.com/USGS-R/ds-gitflows-[username]`.
+2. Click the "Fork" button at the top right (see image below).
+
+![image](https://user-images.githubusercontent.com/13220910/81218905-94147a80-8fa4-11ea-9685-09ae5b335bdf.png)
+
+3. If prompted with `Where should we fork ...`, choose your user account.
+4. When it is complete, you should be on a new webpage. Instead of `USGS-R/ds-gitflows-[username]`, you will now see `[username]/ds-gitflows-[username]` at the top.
+
+Congratulations! You've made your own copy of the main repository. Close this issue and proceed to the next one.

.github/issues_to_create/issue_03.md

@@ -0,0 +1,17 @@
+The next step in our workflow is to clone your fork. This creates a local copy of the repository that is specific to your user on GitHub. The local copy is where you will make changes to the codebase. 
+
+----
+**Action:** Clone this repo!
+
+1. Open the GitHub page for your fork, e.g. `https://github.com/[username]/ds-gitflows-[username]`. *A navigation note*: from your fork, you can easily navigate back to the canonical repository by clicking the link next to "forked from" at the top, just below your forked repository name. From the canonical repo page, you can get back to your fork by clicking the fork button on the canonical repo and choosing your existing fork from the list.
+2. Click the `Clone or download` button. Again, make sure you are ***on your fork***. This means that you see `[username]/ds-gitflows-[username]` at the top of the page with `forked from USGS-R/ds-gitflows-[username]` underneath.
+3. Copy the SSH address, not the HTTPS one (see image below). We should have already set up your SSH keys, but if not, follow [these instructions to generate an SSH key](https://help.github.com/en/github/authenticating-to-github/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) and [these instructions to add the SSH key to your GitHub account](https://help.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account). When you come back to the page, you should have the SSH option.
+
+![image](https://user-images.githubusercontent.com/13220910/81214134-01241200-8f9d-11ea-9acc-994e0ccf368f.png)
+
+4. Open Git Bash on your computer.
+5. Change the working directory ([use `cd`](https://stackoverflow.com/questions/17753986/how-to-change-directory-using-windows-command-line)) to the location where you would like to create the cloned directory. I would recommend creating a folder somewhere in your D drive to put GitHub projects.
+6. Type `git clone [insert URL]` and hit enter, e.g. `git clone [email protected]:[username]/ds-gitflows-[username].git`. Note that you cannot CTRL+V to paste into Git Bash. Right click and choose paste instead.
+7. A new folder with the same name as the repository is now available in your working directory. In the folder, you will find the same files and file structure that you can see on GitHub.
+
+You have now successfully cloned your fork! Close this issue and move on to the next one.

.github/issues_to_create/issue_04.md

@@ -0,0 +1,16 @@
+We refer to online versions of GitHub repositories as "remotes". If you open Git Bash to your project directory (you may need to `cd ds-gitflows-[username]` from the end of the last issue) and run `git remote -v`, you will see a list of remotes and their URLs that are currently associated with your local copy. Currently, you have one remote - your fork of the repository - though you will see both a fetch and push option for it. It is referred to as the `origin` because your local copy *originated* from it. 
+
+What we need to do now is link the canonical repository to your local copy. This closes the loop and enables you to pull down changes that collaborators have merged to the main repo into your local version. We refer to the online canonical version as the `upstream` repo and it is a `remote` because it is online.
+
+----
+**Action:** Link your cloned repository to the upstream remote.
+
+1. Open the GitHub page for the main (or canonical) repository, `https://github.com/USGS-R/ds-gitflows-[username]`
+2. Just like in the previous step, click `Clone or download`
+3. Copy the SSH URL (not the HTTPS URL)
+4. Open Git Bash to your project's working directory.  
+5. Type `git remote add upstream [insert URL]`, e.g. `git remote add upstream https://github.com/USGS-R/ds-gitflows-[username]`. *Reminder:* you cannot CTRL+V to paste into Git Bash. Right click and choose paste instead.
+6. Hit enter.
+7. Now, when you run `git remote -v` you should see a list with both an `upstream` remote and an `origin` remote.
+
+You have now set up your new project for collaborative development! We are ready to start making changes. Close this issue and move on to the next one.

.github/issues_to_create/issue_05.md

@@ -0,0 +1,16 @@
+You are now ready to start contributing your own content to the project! Normally, you would be adding new files, editing lines of code, etc; however, to keep this tutorial programming language-agnostic, we will be editing text in a Markdown document. I think you have already learned about Markdown but if not, visit [this quick article](https://guides.github.com/features/mastering-markdown/) to learn about it.
+
+We will be using the `dryville_story.md` file to illustrate changes to a repository. First, you will make a change and then save it with Git.
+
+----
+**Action:** Add text to the story and commit your change.
+
+1. Before we make any changes, let's check that we are starting from a clean slate. Run `git status` in Git Bash in your project directory. You should see a message that says "nothing to commit". This means that there are no changes on your local copy and it exactly matches the content on your remote fork (the `origin` repo). This is good!
+1. Now, open the `dryville_story.md` file on your computer. Any text editor will do, such as [Notepad++](https://notepad-plus-plus.org/downloads/). Currently, there is a title (denoted by `#`) and two sub-headers (denoted by `##`) with text. You can also see the syntax for hyperlinks, `[text that appears](link/to/the/website)`. To see how this syntax is rendered on GitHub, open the `dryville_story.md` file on GitHub by going to the main repo (`https://github.com/USGS-R/ds-gitflows-[username]`) and clicking the file name.
+1. Now, we will add the next section of the story (we are recreating the story available [here on the USGS Water Science School](https://www.usgs.gov/special-topic/water-science-school/science/story-water-dryville)). Open that link. The next section in the story that we don't have in our file yet is called "Getting Water to Your Homes". Add the title (use `##`), the body text, and the appropriate link for the words "over 8 pounds a gallon" to the `dryville_story.md` file locally. Save the file.
+1. Now, we have made a change in our local repo. If you run `git status` in Git Bash, you should see the words "modified: dryville_story.md". This means that Git detects a new change. At this point, you could run `git diff` to visually see the changes you made: red = original, green = changed (if you do this and see a `:` at the bottom of your bash window, type `q` to get out of the diff view before proceeding). You will also see the words "no changes added to commit". This is because we have not told Git to record these changes; we have not "staged" them. 
+1. We now need to stage these changes so that they can be included in our commit. To stage our changes, run `git add dryville_story.md`. Now when you run `git status`, you see that the "modified: dryville_story.md" change is listed under "Changes to be committed". We are now ready to make a commit.
+1. To make a commit, run `git commit -m "[insert your message here]"`. For this change, we will run `git commit -m "add getting-water-to-your-homes section"`. Any change that was listed under the "Changes to be committed" section when we ran `git status` will be included in this commit.
+1. Run `git status` again. We should be back to where we started. There is "nothing to commit" because we don't have any additional changes to the repository content - we already committed our only changes. However, you will also see that it says "Your branch is ahead of 'origin/main' by 1 commit". We'll talk about that later.
+
+You have now made a commit and recorded your changes with Git! Close this issue and move on to the next one.

.github/issues_to_create/issue_06.md

@@ -0,0 +1,13 @@
+Practice makes perfect - let's make a second commit to our local repo.
+
+----
+**Action:** Add the next section's text and commit this change.
+
+1. If you run `git status` in Git Bash  right now, you should see a message that says "nothing to commit" and also "Your branch is ahead of 'origin/main' by 1 commit". 
+1. Open the `dryville_story.md` file on your computer and add the next section of [the story](https://www.usgs.gov/special-topic/water-science-school/science/story-water-dryville), which is called "Dryville's First Water Works". Keep the same formatting as before (`##` for the title, `[inline text](url)` for hyperlinks). Save the file.
+1. We have now made a second change in our local repo. If you run `git status` in Git Bash, you should see the words "modified: dryville_story.md". This means that Git detects your change. You will also see the words "no changes added to commit". This is because we still need to stage our changes. Note that you will still see "Your branch is ahead of 'origin/main' by 1 commit" - more on that later.
+1. Run `git add dryville_story.md` to stage these changes so that they can be included in our next commit. Now when you run `git status`, you see that the "modified: dryville_story.md" change is listed under "Changes to be committed". We are now ready to make a commit.
+1. Run `git commit -m "add dryvilles-first-water-works section"` to make a second commit.
+1. Run `git status` again. We should be back to where we started. There is "nothing to commit" because we don't have any additional changes to the repository content - we already committed our changes. However, you will now see that it says "Your branch is ahead of 'origin/main' by 2 commits". We'll talk about that next.
+
+You have now made two commits and recorded your changes with Git! Close this issue and move on to the next one.

.github/issues_to_create/issue_07.md

@@ -0,0 +1,13 @@
+At this point, we have made our file changes and are satisfied with the state of our local repository. It is time to join these changes with the main repository so that our collaborators can use them. Before we can merge our changes with the main repository, we need to get our local changes onto our fork on GitHub.
+
+----
+**Action:** Push your changes to your GitHub fork. 
+
+1. If you run `git status` in Git Bash  right now, you should see a message that says "nothing to commit" and also "Your branch is ahead of 'origin/main' by 2 commits". This means that our local version has 2 new changes that do not appear in our remote fork (called the `origin` because our local version *originated* from it). 
+1. To get our local changes to appear on our remote fork, we need to "push" them there. To do so, run `git push`. By default, it will push changes up to the `origin` remote `main` branch (we aren't using branching just yet, so everything is the `main` branch). If you want to be more explicit, you can run `git push [remote name] [branch name]`. For example, `git push origin main` will do the same as `git push`.
+1. After you run this successfully, you will see "To github.com:[username]/ds-gitflows-template.git" near the bottom. It is telling you where those changes went, which is to your remote fork. Yay!
+1. Go to your fork's webpage (`https://github.com/[username]/ds-gitflows-[username]`) and click on the `commits` button (see image below). You should see your two commit messages appear there.
+
+![image](https://user-images.githubusercontent.com/13890601/155426436-2cbe9566-78c1-48d9-9c9d-9119df45f3d6.png)
+
+You have pushed your changes up to GitHub! Close this issue and move on to the next one.