From bfc129ec47cb384eb9e61d4da7dd4b034d5dde32 Mon Sep 17 00:00:00 2001 From: Alessia Visconti Date: Wed, 20 Feb 2019 18:03:16 +0000 Subject: [PATCH 1/9] Drafted first half of the tutorial --- Gemfile | 3 +++ README.md | 22 +++++++++++++++++-- _config.yml | 8 +++++++ index.md | 47 ++++++++++++++++++++++++++++++++++++++++ issues.md | 57 +++++++++++++++++++++++++++++++++++++++++++++++++ own-branch.md | 55 +++++++++++++++++++++++++++++++++++++++++++++++ pull-request.md | 0 same-branch.md | 40 ++++++++++++++++++++++++++++++++++ setting-up.md | 53 +++++++++++++++++++++++++++++++++++++++++++++ 9 files changed, 283 insertions(+), 2 deletions(-) create mode 100644 Gemfile create mode 100755 _config.yml create mode 100644 index.md create mode 100644 issues.md create mode 100644 own-branch.md create mode 100644 pull-request.md create mode 100644 same-branch.md create mode 100644 setting-up.md diff --git a/Gemfile b/Gemfile new file mode 100644 index 0000000..d611737 --- /dev/null +++ b/Gemfile @@ -0,0 +1,3 @@ +source 'https://rubygems.org' +gem 'github-pages', group: :jekyll_plugins +gem "just-the-docs" \ No newline at end of file diff --git a/README.md b/README.md index 5a6d175..61daa49 100644 --- 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 new file mode 100755 index 0000000..df12c92 --- /dev/null +++ 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 new file mode 100644 index 0000000..e14f2dd --- /dev/null +++ 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**. + + + \ No newline at end of file diff --git a/issues.md b/issues.md new file mode 100644 index 0000000..fd7e694 --- /dev/null +++ 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 new file mode 100644 index 0000000..1a9b191 --- /dev/null +++ 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 new file mode 100644 index 0000000..e69de29 diff --git a/same-branch.md b/same-branch.md new file mode 100644 index 0000000..3a1a294 --- /dev/null +++ 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 new file mode 100644 index 0000000..6710eae --- /dev/null +++ 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*! + + + + From 90d971813922fb578d6d9006ca68b295d9836a0a Mon Sep 17 00:00:00 2001 From: Alessia Visconti Date: Wed, 20 Feb 2019 18:12:27 +0000 Subject: [PATCH 2/9] Expanded on the be kind message with concepts taken from the slides --- index.md | 18 ++++++++++++++++-- 1 file changed, 16 insertions(+), 2 deletions(-) diff --git a/index.md b/index.md index e14f2dd..6c2e8a3 100644 --- a/index.md +++ b/index.md @@ -31,7 +31,7 @@ The tutorial will deal with the GitHub web interface, therefore there is no need - Don't know anyone? There are no strangers here, only friends you haven't yet met. -## Ready to start? +## What are we going to do? The tutorial is divided in five parts: @@ -41,7 +41,21 @@ The tutorial is divided in five parts: 4. Working on your own branch 5. Merging all together -But before delving into it, please remember: **be kind**. + +## Ready to start? + +Before delving into the tutorial, please remember that **good** collaborations: + +* allow a safe space for constructive and honest discussion, therefore +* do not blame and shame +* make room and time for teaching and learning +* accept that there will be mistakes & mishaps (helping each other is a great way to learn) + +Indeed, a **good** collaboration + +* is first and foremost about working with and respecting other people +* is NOT a _"soft"_, optional, skill: it is essential! + \ No newline at end of file From 08d562e9f30fcea7e57f4f0e2ba8491a343ad839 Mon Sep 17 00:00:00 2001 From: Alessia Visconti Date: Wed, 20 Feb 2019 18:29:13 +0000 Subject: [PATCH 3/9] Description are no longer super detailed --- issues.md | 17 ++++++----------- own-branch.md | 16 +++++----------- same-branch.md | 8 ++++---- setting-up.md | 16 ++++++---------- 4 files changed, 21 insertions(+), 36 deletions(-) diff --git a/issues.md b/issues.md index fd7e694..53fdde9 100644 --- a/issues.md +++ b/issues.md @@ -11,15 +11,14 @@ permalink: /issues **Learning goals** * Creating an issue -* Addressing an issue +* Assigning 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. +* Click on the `Issue` tab. 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: * 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: @@ -32,26 +31,22 @@ permalink: /issues | 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. +* Submit the new issue * 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. +* Once everyone has completed step 1, you should be able to see all the questions (hope that there are not too many duplicates!) +* Select a question you like and assign the issue to yourself. To avoid having everyone dealing with the same question, **quickly** decide who is going to answer what **before** assigning the issue to yourself :sweat_smile: * 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! +* Once everyone has completed step 2, 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 index 1a9b191..0a8c259 100644 --- a/own-branch.md +++ b/own-branch.md @@ -26,9 +26,8 @@ permalink: /own-branch ## 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 +* Note a button `Branch: master`. So far we have used only one branch (`master`) but it is now time to get a branch on our own! +* Create a branch, using your name as the branch name * 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! @@ -36,20 +35,15 @@ permalink: /own-branch ## 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: +* Create a new file and use it to 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. +* After step 3, your branch will be one commit ahead of `master`. Can you see it? +* Let's now compare your branch with `master`. Any difference? * Does everything look good? Everything there? * Step 4 completed. Time to move on and push these changes to the original repo. - - diff --git a/same-branch.md b/same-branch.md index 3a1a294..00bd1bb 100644 --- a/same-branch.md +++ b/same-branch.md @@ -19,12 +19,12 @@ permalink: /same-branch ## 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? +* 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, you can see the content of the README file, 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: +* 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 +* Commit changes * Step 1 completed. Not too hard, right? ## Step 2: Observing the results @@ -32,7 +32,7 @@ permalink: /same-branch * 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 +* What has happened? What can possibly go wrong in a real world scenario? Discuss with your team members :loudspeaker: * 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 index 6710eae..1758ca8 100644 --- a/setting-up.md +++ b/setting-up.md @@ -20,25 +20,21 @@ permalink: /setting-up ## 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 +* The *chosen one* should now go to their GitHub page (`https://github.com/loginname`) and click on the `Repository` tab. This page lists all your repository -- it may already include some :nerd_face: +* Create a new repo(sitory) * 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 +* Create the repository! * 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) +* You landed on your repo main page. Only one person is allowed to _"collaborate"_ to it: 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 +* Look then for adding `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: From ae15309eb79dc7e4d74faad244e4c0118db8b367 Mon Sep 17 00:00:00 2001 From: Alessia Visconti Date: Wed, 20 Feb 2019 18:30:33 +0000 Subject: [PATCH 4/9] Forking is no longer a thing --- own-branch.md | 21 +++++++-------------- 1 file changed, 7 insertions(+), 14 deletions(-) diff --git a/own-branch.md b/own-branch.md index 0a8c259..70da320 100644 --- a/own-branch.md +++ b/own-branch.md @@ -10,7 +10,6 @@ permalink: /own-branch --- **Learning goals** -* Forking a repository * Creating branches * Creating files, and committing changes * Comparing branches @@ -18,32 +17,26 @@ permalink: /own-branch --- -## 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 +## Step 1. Creating a branch * Note a button `Branch: master`. So far we have used only one branch (`master`) but it is now time to get a branch on our own! * Create a branch, using your name as the branch name * 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 1 completed. Time of doing some *serious* job here! -## Step 3. Creating and committing a new file +## Step 2. Creating and committing a new file * Remember we created this branch to deal with an issue we self-assigned? Time to address it! * Create a new file and use it to 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 2 completed. Will your literary efforts be enough? -## Step 4. Comparing branches +## Step 3. Comparing branches -* After step 3, your branch will be one commit ahead of `master`. Can you see it? +* After step 2, your branch will be one commit ahead of `master`. Can you see it? * Let's now compare your branch with `master`. Any difference? * Does everything look good? Everything there? -* Step 4 completed. Time to move on and push these changes to the original repo. +* Step 3 completed. Time to move on and push these changes to the original repo. From 83a504e59e00437b26aba37899793cdac9ee26b9 Mon Sep 17 00:00:00 2001 From: Ester Date: Wed, 20 Feb 2019 21:27:42 +0000 Subject: [PATCH 5/9] Add pictures to issues.md --- issues.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/issues.md b/issues.md index 53fdde9..470600d 100644 --- a/issues.md +++ b/issues.md @@ -19,6 +19,9 @@ permalink: /issues # Step 1. Creating an issue * Click on the `Issue` tab. 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: + +![create issue](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/create_issue.png "Create Issue") + * 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: @@ -41,6 +44,9 @@ permalink: /issues * Select a question you like and assign the issue to yourself. To avoid having everyone dealing with the same question, **quickly** decide who is going to answer what **before** assigning the issue to yourself :sweat_smile: * 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! + +![assign issue](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/assign_issue.png "Assign Issue") + * Step 2 completed! From aee491a778cb6ddded9ef6e753d0bee411c31375 Mon Sep 17 00:00:00 2001 From: Ester Date: Wed, 20 Feb 2019 21:34:31 +0000 Subject: [PATCH 6/9] Add images to own-branch.md --- own-branch.md | 8 ++++++++ 1 file changed, 8 insertions(+) diff --git a/own-branch.md b/own-branch.md index 70da320..7e27a8b 100644 --- a/own-branch.md +++ b/own-branch.md @@ -23,12 +23,18 @@ permalink: /own-branch * Create a branch, using your name as the branch name * 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! + +![create branch](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/create_branch.png "Create Branch") + * Step 1 completed. Time of doing some *serious* job here! ## Step 2. Creating and committing a new file * Remember we created this branch to deal with an issue we self-assigned? Time to address it! * Create a new file and use it to 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: + +![create file](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/create_file.png "Create File") + * Commit with a message/description as done before. Are you in the correct branch, the one with your name? * Step 2 completed. Will your literary efforts be enough? @@ -36,6 +42,8 @@ permalink: /own-branch * After step 2, your branch will be one commit ahead of `master`. Can you see it? * Let's now compare your branch with `master`. Any difference? + +![compare](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/compare.png "Compare") * Does everything look good? Everything there? * Step 3 completed. Time to move on and push these changes to the original repo. From 36123b005d970af1e388984200907382e8b40633 Mon Sep 17 00:00:00 2001 From: Ester Date: Wed, 20 Feb 2019 21:40:47 +0000 Subject: [PATCH 7/9] Add border to images --- own-branch.md | 10 ++++++++++ 1 file changed, 10 insertions(+) diff --git a/own-branch.md b/own-branch.md index 7e27a8b..1fe3152 100644 --- a/own-branch.md +++ b/own-branch.md @@ -24,8 +24,12 @@ permalink: /own-branch * 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! + + ![create branch](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/create_branch.png "Create Branch") + + * Step 1 completed. Time of doing some *serious* job here! ## Step 2. Creating and committing a new file @@ -33,8 +37,14 @@ permalink: /own-branch * Remember we created this branch to deal with an issue we self-assigned? Time to address it! * Create a new file and use it to 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: + + + ![create file](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/create_file.png "Create File") + + + * Commit with a message/description as done before. Are you in the correct branch, the one with your name? * Step 2 completed. Will your literary efforts be enough? From e7525b2fa738b7e258f37aa51182d958b694c8ec Mon Sep 17 00:00:00 2001 From: Ester Date: Wed, 20 Feb 2019 21:45:31 +0000 Subject: [PATCH 8/9] Add border --- own-branch.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/own-branch.md b/own-branch.md index 1fe3152..279c907 100644 --- a/own-branch.md +++ b/own-branch.md @@ -53,7 +53,13 @@ permalink: /own-branch * After step 2, your branch will be one commit ahead of `master`. Can you see it? * Let's now compare your branch with `master`. Any difference? + + ![compare](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/compare.png "Compare") + + + + * Does everything look good? Everything there? * Step 3 completed. Time to move on and push these changes to the original repo. From cd0c819a009905aa9f1c7b94669e4caef7f83360 Mon Sep 17 00:00:00 2001 From: Ester Date: Wed, 20 Feb 2019 21:56:09 +0000 Subject: [PATCH 9/9] Add images to setting-up.md --- setting-up.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/setting-up.md b/setting-up.md index 1758ca8..3ab969d 100644 --- a/setting-up.md +++ b/setting-up.md @@ -22,11 +22,26 @@ permalink: /setting-up * 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. This page lists all your repository -- it may already include some :nerd_face: * Create a new repo(sitory) + + + +![create repo](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/create_repo.png "create repo") + + + * 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?) +* Choose an MIT license to keep it simple. Licenses are very important so next time you create a repo take your time to read the options and choose the one that fit your project best. + + + +![choose license](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/license.png "choose license") + + + * Create the repository! * Step 1 completed. Give each other a high five :raised_hands: @@ -36,6 +51,13 @@ permalink: /setting-up * The repo's owner should now click on the `Setting` tab * Look then for adding `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 + + + +![add collaborators](https://github.com/feiphoon/github-workshop/blob/gh-pages/screenshots/collaborators.png "Add colaborators") + + + * Step 2 completed. Time for everyone to roll up their sleeves :muscle: