Drafted first half of the tutorial

alesssia · alesssia · commit bfc129ec47cb · 2019-02-20T18:03:16.000Z
diff --git a/Gemfile b/Gemfile
@@ -0,0 +1,3 @@
+source 'https://rubygems.org'
+gem 'github-pages', group: :jekyll_plugins
+gem "just-the-docs"
diff --git a/README.md b/README.md
@@ -1,7 +1,21 @@
-# github-workshop
+---
+layout: default
+title: README
+nav_exclude: true
+published: false
+---
+
+# GitHub for Collaborative Data Science & Engineering in Industry & Academia
+
+## Steps that we need to deal with:
+
+### Not in the tutorial
 
 0. Everyone should sign up for a GitHub account (before the workshop)
 1. 20 or so minutes of basics (Decide about what and who)  "We don't make mistakes, just happy little accidents"
+
+### In the tutorial (included)
+
 2. Split everyone in groups (tables)
 3. Create a repository (one per table). It should have a README, LICENSE, description and gitignore.
 4. Add collaborators
@@ -11,7 +25,11 @@
 8. Everyone create a branch to address their assigned issue
 9. Create a folder and file (come back to give them path instructions)
 10. Commit the new file
-11. Do a compare and open a pull request and link to issue in description
+11.1 Do a compare [and open a pull request and link to issue in description]
+
+### In the tutorial (to be included)
+
+11.2 [Do a compare] and open a pull request and link to issue in description
 11.b Checkpoint/timecheck (How many tables have a pull request)
 12. Assign a reviewer (The person who created the issue)
 13. The reviewer changes branches and learns "find/navigate"
diff --git a/_config.yml b/_config.yml
@@ -0,0 +1,8 @@
+theme: just-the-docs
+
+title: GitHub Collaborative Workshop
+
+markdown:    kramdown
+highlighter: rouge
+permalink: pretty
+
diff --git a/index.md b/index.md
@@ -0,0 +1,47 @@
+---
+layout: default
+title: Home
+nav_order: 1
+permalink: index
+---
+
+# GitHub for Collaborative Data Science & Engineering in Industry & Academia
+
+Welcome to our *collaborative* session on data science and engineering :wave:
+
+This tutorial will walk you through:
+
+* creating a GitHub repository
+* adding contributors to a GitHub repository -- this is a *collaborative* session, after all :grin:
+* creating files, editing and committing changes
+* opening and assigning issues
+* solving issues in a *collaborative* fashion via
+	- branch managements
+	- pull requests
+	- code reviews
+
+The tutorial will deal with the GitHub web interface, therefore there is no need to install anything on your machine, nor to type anything in the command line. We may address these in a more advanced session. 
+
+## Prerequisites
+
+1. Your own laptop, with battery charged, a working web browser (Chrome, Firefox, ...), and a good internet connection 
+2. A GitHub account. If you don't have one you can sign up here for free: [https://github.com/join](https://github.com/join)
+3. Friends. This is a *collaborative* session, don't forget that! 
+	- Please create a team of three/four people 
+	- Don't know anyone? There are no strangers here, only friends you haven't yet met.
+	
+
+## Ready to start?
+
+The tutorial is divided in five parts: 
+
+1. Setting up
+2. Working all on the same branch
+3. Creating and dealing with issue
+4. Working on your own branch
+5. Merging all together
+
+But before delving into it, please remember: **be kind**.
+
+
+	
diff --git a/issues.md b/issues.md
@@ -0,0 +1,57 @@
+---
+layout: default
+title: Creating and dealing with issue
+nav_order: 4
+permalink: /issues
+---
+
+# Creating and dealing with issues
+
+---
+**Learning goals**
+
+* Creating an issue
+* Addressing an issue
+
+---
+
+
+# Step 1. Creating an issue
+
+* Click on the `Issue` tab, on the top of the page. This page lists all the issues, which are used to track todos, bugs, feature requests, and whatever you think fit. When you are opening an issue on a public repo, please look for a code of conduct, or for a bug reporting check list and comply with them  :relaxed: 
+* Click on the `New issue` green button on the right of the page.
+* You are a team, therefore it is good to get to know one another a bit. Therefore, your *feature requests* will be asking (personal?) questions to  other team members
+* Think of a question and use it as a title. Be creative, or use one of the questions below
+* How the other team member should address the question? Describe it in the comment. Look at the examples below but please, no poem, the deal is to learn how to collaborate via GitHub, not to win the Pulitzer :stuck_out_tongue:
+
+|  Question | Description  |
+|:---|:---|
+| What is your favourite food?  | Can you list the main ingredients? How often do you eat it? Can you cook it?  | 
+| Where were you born? | Please, tell me how does it look!  | 
+| What is your background? | I can see that you joined the AIClub, so you may be keen on AI, data science and the likes, but what did you study? |
+| What do you do? | I can see that you joined the AIClub, so you may be keen on AI, data science and the likes, but what do you do to survive? |
+| Why did you join this workshop?  |  Please, explain me how proficient (if any) you are with GitHub and what you are expecting from this workshop  | 
+
+* Click on the `Submit new issue` green button.
+* Step 1 completed. Your issue has been assigned a tracking number (gotten how the numbering works?)
+
+
+# Step 2. Assigning an issue
+
+* Once everyone has completed step 1, click again on the `Issue` tab. Now you should be able to see all the questions (hope that there are not too many duplicates!)
+* To avoid having everyone dealing with the same question, **quickly** decide who is going to answer what :sweat_smile:
+* Select the question you like and click on it
+* On the right menu, you will see a `Assignees No one — assign yourself`. Click on it and then on your name.
+* Great, you just committed to answer the question :nerd_face:
+* Write a nice comment explaining that you are dealing with the issue right now. It is nice knowing that an issue has been assigned to someone, but it is even better knowing that someone is actually working on it!
+* Click on the `Comment` green button. 
+* Note the grey `Close and comment` beside: this is a great one to click on, we will do it later :grin:
+* Step 2 completed!
+
+
+# Step 3. Checking whether all issues have been assigned
+
+* Once everyone has completed step 2, click again on the `Issue` tab. Now you should be able to see all the questions and who is dealing with them!
+* Step 3 completed. This was easy, wasn't it?
+
+
diff --git a/own-branch.md b/own-branch.md
@@ -0,0 +1,55 @@
+---
+layout: default
+title: Working on your own branch
+nav_order: 4
+permalink: /own-branch
+---
+
+# Working on your own branch
+
+---
+**Learning goals**
+
+* Forking a repository
+* Creating branches
+* Creating files, and committing changes
+* Comparing branches
+
+---
+
+
+## Step 1. Forking the repository
+
+* This step should be done by everyone apart the repo owner
+* Click on the `Fork` button on the top right of the page. This will create a copy of the repository on your own GitHub account (see that the name of the repository is now *your username/repo name*?)
+* Step 1 completed. For this part of the tutorial, we will work on this copy of the repo and no longer on the original one (apart, again, the repo owner, who will work on the original repo)
+
+## Step 2. Creating a branch
+
+* Note a button `Branch: master` on the top-right of the repo main page, above the list of files. So far we have used only one branch (`master`) but it is now time to get a branch on our own!
+* Click on the button, and when asked to find or create a branch, type your name
+* A `Create branch: your name` button will appear, click on it
+* Congratulation you create your own branch :tada:
+* Note the button `Branch` again: now no longer report `master` but it has your new branch name: you create and checked it out at the same time!
+* Step 2 completed. Time of doing some *serious* job here!
+
+## Step 3. Creating and committing a new file
+
+* Remember we created this branch to deal with an issue we self-assigned? Time to address it!
+* Click on the button `Create new file`, just below the *number of releases*
+* Name your file
+* Answer the question you have self-assigned. Write a few lines (so we can have some material to work on in the next steps) but remember that the goal is not to win the Costa Book Awards :stuck_out_tongue:
+* Commit with a message/description as done before. Are you in the correct branch, the one with your name?
+* Step 3 completed. Will your literary efforts be enough? 
+
+## Step 4. Comparing branches
+
+* After step 3, your branch will be one commit ahead of `master. Can you see it?
+* Click on the `Compare` button.
+* You will land in a page highligthing all the differences between the `master` and your own branch.
+* Does everything look good? Everything there? 
+* Step 4 completed. Time to move on and push these changes to the original repo.  
+
+
+
+
diff --git a/pull-request.md b/pull-request.md
diff --git a/same-branch.md b/same-branch.md
@@ -0,0 +1,40 @@
+---
+layout: default
+title: Working all on the same branch
+nav_order: 3
+permalink: /same-branch
+---
+
+
+# Working all on the same branch
+
+---
+**Learning goals**
+
+* Editing files and committing changes
+* Understanding basic issues underlining collaborations
+
+---
+
+
+## Step 1: Editing a file and committing changes
+
+* The work carried on on our repo will be a collaborative one, therefore all the members of the team need to be acknowledged. On the main repo's page, along with the stats we described before (numbers of commits, branches, ...), you will see the list of files included in the repo (now README and license), the commit message(s) (more later), and when the commit(s) have been done. Just below there is the  README page content, which now just reports the repo's name and description. What better place to list all the contributors?
+* Press the pencil on the left of the `README.md` box
+* In a new line, immediately below the repo's description, add your name
+* On the bottom of the page include a commit message (you can use the suggested *Update README.md* or be more precise) and an optional extended description (what did you do?). Detailed commits are always highly appreciated, as the person that made them :wink:
+* We will commit directly to the master branch (no action needed, but note the option of creating another branch)
+* Click on the `Commit changes` green button
+* Step 1 completed. Not too hard, right? 
+
+## Step 2: Observing the results
+
+* Wait for everyone to have completed step 1
+* Refresh the main repo page
+* Is your name still immediately below the repo's description? 
+* What has happened? What can possibly go wrong in a real world scenario? Discuss with your team members
+* Also, how many commits there are now?
+* Step 2 completed. Let's move to a more organised (and less dangerous) way to collaborate
+
+
+
diff --git a/setting-up.md b/setting-up.md
@@ -0,0 +1,53 @@
+---
+layout: default
+title: Setting Up
+nav_order: 2
+permalink: /setting-up
+---
+
+# Setting up
+
+---
+**Learning goals**
+
+* Initialise a GitHub repository
+* Adding contributors, and accepting invitation to contribute
+
+---
+
+
+
+## Step 1: Initialising a repository 
+
+* You will collaborate on a single repository, therefore you will need to create **one and only** one: choose one person in your team to do so (but watch out what they are doing)
+* The *chosen one* should now go to their GitHub page (`https://github.com/loginname`) and click on the `Repository` tab, on the top of the page. This page lists all your repository -- it may already include some :nerd_face:
+* Click on the `New` green button on the top right
+* Your repository will need a name: agree on one! If you are having a creative block, names like *"github-collaborative-workshop"*, or *"AIClub-githib-workshop"* will be amazing, trust us :sweat_smile:
+* Your repository will also need a description: why not *"A collaborative repo"*?
+* Your repository can be *public* (everyone can access it) or *private* (only you and your collaborators will be able to access it). Since early 2019, GitHub allows an unlimited number of private repositories, but don't be shy -- and think of all the good you get from open access code. Time to give some love back?
+* GitHub allows initialising a repository with a README file. Please, do so
+* GitHub allows generating a `.gitignore` (which lists all the files that should not be included on a repo) and a `licence` file. Let's ignore the former but let's include the latter (quite a list, isn't it?)
+* Click on the `Create repository` green button
+* Step 1 completed. Give each other a high five :raised_hands:
+
+## Step 2: Adding contributors
+
+* You landed on your repo main page. Under the repo name & description there is a summary of its *status*: 
+	* number of commits: 1, the *Initial commit* you triggered when pressing the `Create repository` button
+	* number of branches: 1, the so-called `master` branch
+	* number of releases: 0, we need some time
+	* number of collaborators: 1, the repo's owner, time to change this :two_women_holding_hands: :couple: :two_men_holding_hands:
+* The repo's owner should now click on the `Setting` tab, on the top of the page 
+* On the left menu, click on `Collaborators` (you may be asked to type your password)
+* Add the other members of the team, one by one, using their GitHub username or email
+* Step 2 completed. Time for everyone to roll up their sleeves :muscle:
+
+
+## Step 3: Accepting an invitation to contribute
+
+* All the member of the team should receive an email inviting them to collaborate. Please accept: the more, the merrier!
+* Step 3 completed. Ready for the real work? From now on, everyone has do to their homework, so no more looking at the *chosen one*!
+
+
+
+

Original file line number	Diff line number	Diff line change
`@@ -0,0 +1,3 @@`
	`1`	`+source 'https://rubygems.org'`
	`2`	`+gem 'github-pages', group: :jekyll_plugins`
	`3`	`+gem "just-the-docs"`