From f67420d7eb121250bb6597d3146f2c9084f78c61 Mon Sep 17 00:00:00 2001 From: Richard Darst Date: Thu, 7 Mar 2024 17:50:47 +0200 Subject: [PATCH] various day 1 updates --- content/browsing.md | 140 +++++++++++++++++++++++++------------------ content/commits.md | 24 +++++--- content/merging.md | 60 ++++++++++++------- content/reference.md | 16 +++++ 4 files changed, 154 insertions(+), 86 deletions(-) diff --git a/content/browsing.md b/content/browsing.md index d4cf6c1a..5f4bf4f9 100644 --- a/content/browsing.md +++ b/content/browsing.md @@ -1,14 +1,15 @@ # Copy and browse an existing project -The first thing most people do is **contribute to an existing -project**. This, and following lessons, go over this. We use an -an example recipe book on GitHub. +In this episode, we will look at an existing repository to +understand how all of pieces work. Along the way, we will make a copy +(a {term}`fork`) of the {term}`repository` for us, which will be used for our +own changes in the next episode. :::{objectives} * See a real git repository and understand what is inside of it. * Understand how version control allows advanced inspection of a repository. -* See how git allows multiple people to take collaborate. +* See how git allows multiple people to collaborate easily. ::: :::{instructor-note} @@ -19,9 +20,6 @@ Preparation: - Create one or two issues - Create one or two pull requests - Try to search for something in the recipe to trigger a search index update - -Before starting the exercise session: -- Show how to fork the repository to own account ::: ```{highlight} console @@ -37,53 +35,27 @@ We will add to this page: - summary + ## Introduction -* You will probably interact with more repositories owned by other - people than with your own -* It's easier to get to know your own repositories +* We used to start by directly going and creating a repository. This + was abstract and hard to understand. +* Instead, we'll show you all the cool stuff in a git repository + first, and then start adding files. +* We use an example recipe book we created just for this course. +* By the end of the course, you'll know how to contribute your own + recipes to it. -## Exercise -Work on this by yourself. The solution below goes over most of the -answers, but the hints should get you most of the way. Refer to the -solution if you get stuck. +## GitHub, VS Code, Command line, and more We offer **three different flows** of how to do this exercise. For the CodeRefinery workshop day 1, we use and demonstrate the **GitHub flow** only and recommend you do that. -:::{exercise} Exercise: Browsing an existing project (25 min) -First **make a copy** to your own account to work on **by forking** - +In the future we'll add more flows, for example Jupyter and RStudio. -Then browse the project and explore commits and branches. Take notes and prepare questions. - -1. Browse the commit history: Are commit messages understandable? - (Hint: "Commit history" (like "25 commits") above the file list.) -1. Compare the commit history with the network graph ("Insights" -> "Network"). Can you find the branches? -1. How can you find out when a recipe was last modified? -1. How many changes did the Guacamole recipe receive (you find it under "sides")? - Try to click on some of the commits to see what changed. - (Hint: "History" in the view of a single file.) -1. Which recipes include the ingredient "salt"? - (Hint: the GitHub search. From the repository view, it should offer - the filter "repo:coderefinery/recipe-book" by default. What if you - add a search term?) -1. In the Guacamole recipe, find out who modified each line last and when - (click on file, then click "Blame" button). Find out who added the cilantro - and in which commit. - (Hint: "Blame" view in the file view) -1. How many people have contributed to the repository? - (Hint: under "Insights") -1. Can you use these recipes yourself? Are you allowed to share - modifications? - (Hint: look for a license file) -1. Browse issues and pull requests, any idea what these might be good - for? - (Hint: tabs in the repository view) -::: ## Setup @@ -92,22 +64,28 @@ Then browse the project and explore commits and branches. Take notes and prepare In the CodeRefinery workshop itself, we follow the **GitHub** flow. **VS Code** and **Command line** are for reference, for people who -already know enough to follow. They do not have full information and -screenshots, and may not be complete. +already know these tools. They do not have full information and +screenshots, and may not be complete yet. ::: -First, we need to make our own copy of the repository. This will -become important later, when we make our own changes. +First, we need to make our own copy of the repository. +This will become important later, when we make our own changes. + +1. Go to the repository view on GitHub: +1. First, on GitHub, click the button that says "Fork". It is towards + the top-right of the screen. +1. You should shortly be redirected to your copy of the repository. -1. Go to the repository view on GitHub (everyone should do this, - regardless of which flow you are using): -1. First, on GitHub, click the button that says "Fork". -1. TODO. +At all times you should be aware of if you looking at *your* repository +or the *CodeRefinery {term}`upstream`*. +* Your repository: https://github.com/**USERNAME**/recipe-book +* CodeRefinery repository: https://github.com/**coderefinery**/recipe-book :::::{tabs} ::::{group-tab} GitHub -You only need to open your own view. The browser URL should look like -`https://github.com/USER/recipe-book`, where `USER` is your GitHub username. +You only need to open your own view, as described above. The browser +URL should look like `https://github.com/USER/recipe-book`, where +`USER` is your GitHub username. :::: ::::{group-tab} VS Code @@ -136,7 +114,8 @@ We need to start by making a copy of this repository locally. 1. Start the terminal in which you use git (Terminal application, or Git-Bash). 1. Change to the directory where you would want the repository to be - (`cd code` for example) + (`cd ~/code` for example, if the `~/code` directory is where you + store your files). 1. Run the following command: `git clone https://github.com/USER/recipe-book`, where `USER` is your username. You might need to use a SSH clone command instead of @@ -146,7 +125,53 @@ We need to start by making a copy of this repository locally. ::::: -## Solution +## Exercise + +Work on this by yourself or in your team. + +:::{instructor-note} +Before starting the exercise session: +- Make sure you have shown how to fork the repository to own account + (above). +::: + +:::{exercise} Exercise: Browsing an existing project (25 min) + +Then browse the project and explore commits and branches. Take notes and prepare questions. + +1. Browse the commit history: Are commit messages understandable? + (Hint: "Commit history" (like "25 commits") above the file list.) +1. Compare the commit history with the network graph ("Insights" -> "Network"). Can you find the branches? +1. How can you find out when a recipe was last modified? +1. How many changes did the Guacamole recipe receive (you find it under "sides")? + Try to click on some of the commits to see what changed. + (Hint: "History" in the view of a single file.) +1. Which recipes include the ingredient "salt"? + (Hint: the GitHub search. From the repository view, it should offer + the filter "repo:coderefinery/recipe-book" by default. What if you + add a search term?) +1. In the Guacamole recipe, find out who modified each line last and when + (click on file, then click "Blame" button). Find out who added the cilantro + and in which commit. + (Hint: "Blame" view in the file view) +1. How many people have contributed to the repository? + (Hint: under "Insights") +1. Can you use these recipes yourself? Are you allowed to share + modifications? + (Hint: look for a license file) +1. Browse issues and pull requests, any idea what these might be good + for? + (Hint: tabs in the repository view) +::: + + +The solution below goes over most of the answers, and you are +encouraged to use it when the hints aren't enough - this is by +design. + + + +## Solution and walk-through ### (1) Basic browsing @@ -248,7 +273,8 @@ According to the view above, it seems to have five changes (as of ### (5) Which recipes include the ingredient "salt" ? Version control makes it very easy to find all occurrences of a single -word. This is useful for things like tracing through code +word. This is useful for things like finding where things are +defined. :::::{tabs} ::::{group-tab} GitHub @@ -347,7 +373,7 @@ repository, the one of "CodeRefinery" (not your fork): . Issues and Pull Requests are different for each GitHub copy. -* Click on the Issues" tab. These are notes that people have added, +* Click on the "Issues" tab. These are notes that people have added, which allow discussion about the project. * Click on the "Pull requests" tab. This allows anyone to *propose changes*, but only the repository owners can accept. diff --git a/content/commits.md b/content/commits.md index 6a981b0d..a131ef1b 100644 --- a/content/commits.md +++ b/content/commits.md @@ -20,6 +20,16 @@ Before starting the exercise session: ```{highlight} console ``` +We will add to this page: +- intro +- screenshots +- tab on how to do this locally +- hints +- solution +- discussion +- summary + + ## Background @@ -44,17 +54,13 @@ Make sure that you work now **on your fork** of the recipe-book repository. 1. Try to rename the branch that you created and then browse the network again. ::: -We will add to this page: -- intro -- screenshots -- tab on how to do this locally -- hints -- solution -- discussion -- summary +The solution below goes over most of the answers, and you are +encouraged to use it when the hints aren't enough - this is by +design. + -## Solution +## Solution and walk-through ### (1) Create a branch and add recipe to the branch diff --git a/content/merging.md b/content/merging.md index e1cc641c..792368fd 100644 --- a/content/merging.md +++ b/content/merging.md @@ -2,10 +2,10 @@ When different people do different things at the same time, it means we have to somehow combine the changes later. This part goes over that -**merging**. +{term}`merging`. :::{objectives} -* Understand that merging is done throguh **pull requests** (= change proposal). +* Understand that merging is done through a {term}`pull request` (= change proposal). * Create and merge a pull request within your own repository. * Understand (and optionally) do the same for the main public repository. ::: @@ -18,10 +18,34 @@ Before starting the exercise session: ```{highlight} console ``` +We will add to this page: +- intro +- screenshots +- tab on how to do this locally +- hints +- solution +- discussion +- summary + + + +## Background + +* In the last episode, we added a new recipe on a branch. This allows + us to test it before it becomes "live". +* Now, we want to bring that change into the "main" branch. +* We find it's not that hard! But you do have to keep track of the + steps and make sure that you work very precisely. + + ## Terminology * {term}`upstream`: The original repository from where your code comes +* {term}`pull request` +* {term}`merge` + + ## Exercise @@ -37,6 +61,9 @@ some GitHub-specific notes, but most is possibly with any flow. :::::{tabs} ::::{group-tab} GitHub +First, we make something called a {term}`pull request`, which allows +review and commenting before the actual merge. + :::{exercise} Exercise: Merging branches with pull requests (20 min) We assume that in the previous exercise you have created a new branch with a recipe. In our previous example, it is called `new-recipe`. @@ -79,7 +106,8 @@ As usual, this is basic hints. You should refer to the solution as needed. ::::{group-tab} Local (VS Code, Command line) When working locally, it's easier to merge branches: we can just do -the merge, without making a pull request. +the merge, without making a pull request. But we don't have that step +of review and commenting. :::{exercise} @@ -96,30 +124,16 @@ Then: upstream repository. *This is very complex right now since your change has to get to GitHub, and we haven't shown that yet. We don't give a solution for this.* - - ::: :::: - ::::: -Demo: -- conflict -- delete branches -- create release (or optional exercise step) - -We will add to this page: -- intro -- screenshots -- tab on how to do this locally -- hints -- solution -- discussion -- summary +The solution below goes over most of the answers, and you are +encouraged to use it when the hints aren't enough - this is by design. -## Solution +## Solution and walk-through ### (1) Navigate to your branch @@ -238,6 +252,12 @@ a recipe to everyone. ::::: +## Demo: resolving a conflict + +## Demo: deleting a branch + +## Demo: create a release + ## Discussion diff --git a/content/reference.md b/content/reference.md index 8e0d5284..da240562 100644 --- a/content/reference.md +++ b/content/reference.md @@ -56,6 +56,17 @@ upstream {term}`fork` the repository, it is your upstream and it is easy to send changes back to there. +fork + As a noun: a one person's copy of a repository. + As a verb: making that copy. + As a verb on GitHub: Making a copy of a repository linked to the + original. It is easy to send changes to the original + +pull request + A GitHub concept: change proposal. A proposal to merge one branch + into another. Usually used to contribute code back to + {term}`upstream`. + master Default name for main branch on Git. Depending on the configuration and service, the default branch is sometimes **main**. @@ -67,6 +78,11 @@ main In this lesson we configure Git so that the default branch is called **main** to be more consistent with GitHub and GitLab. +merge +merging + Bringing changes from one branch into another, either as a noun or + verb. + ::::: ## Commands we use