From a180e5ab3a2111edbc5a0144821c03c511b1bc96 Mon Sep 17 00:00:00 2001 From: Tom van Woudenberg Date: Fri, 13 Dec 2024 17:36:56 +0100 Subject: [PATCH] Added exercise 5 --- book/exercises/001.md | 2 +- book/exercises/002.md | 2 +- book/exercises/003.md | 2 +- book/exercises/004.md | 4 ++-- book/exercises/005.md | 28 ++++++++++++++++++++++++++++ 5 files changed, 33 insertions(+), 5 deletions(-) create mode 100644 book/exercises/005.md diff --git a/book/exercises/001.md b/book/exercises/001.md index 2fc2ce7..eb58f9d 100644 --- a/book/exercises/001.md +++ b/book/exercises/001.md @@ -2,7 +2,7 @@ Let's start with the most basic edit: add some text to a file and see that the website is updated. -Can you add some content to the intro page? +> Can you add some content to the intro page? 1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `intro.md` - {octicon}`pencil;1em` `Edit this file` 2. Add some text. Feeling brave? Have a look at the [MyST cheat sheet](https://jupyterbook.org/en/stable/reference/cheatsheet.html). Don't worry if that feels daunting, there will be exercises on this! diff --git a/book/exercises/002.md b/book/exercises/002.md index 271d0db..46ee523 100644 --- a/book/exercises/002.md +++ b/book/exercises/002.md @@ -2,7 +2,7 @@ Let's continue by adding one additional step. Let's add a file to the table of contents! the `_toc.yml` contains a list of all the files to be shown in your book-website. Let's add a file which is not in the table of contents yet! -Can you add the file named `file_to_be_added_to_toc.md` to the book website? +> Can you add the file named `file_to_be_added_to_toc.md` to the book website? 1. Go to the (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` directory of your GitHub repository and find the location of `file_to_be_added_to_toc.md` 2. Go to the the file `book/_toc.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file` diff --git a/book/exercises/003.md b/book/exercises/003.md index 84e36d8..dd39b96 100644 --- a/book/exercises/003.md +++ b/book/exercises/003.md @@ -2,7 +2,7 @@ As we've added some content by now, let's make this book a bit more personal! We'll make some changes to the `_config.yml` file which changes the configuration of the book website. -Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer? +> Can you edit the repository url defined in the `_config.yml`, change the title shown below the logo and change the author as shown in the footer? 1. Go to the the file `book/_config.yml` on your GitHub repository (`https://github.com//`) - {octicon}`code;1em` `Code` - `Book` - `_config.yml` - {octicon}`pencil;1em` `Edit this file` 2. In the `Edit` field, change the author which will be shown in the footer of the book website. diff --git a/book/exercises/004.md b/book/exercises/004.md index 97dd68c..05d8ec3 100644 --- a/book/exercises/004.md +++ b/book/exercises/004.md @@ -2,11 +2,11 @@ By now, we've covered the essentials: content files, `_toc.yml` and `_config.yml`. But what if you want to make some changes but don't want to share them directly with the general public of your book website? Or what if you have some work-in-progress that you want to share with colleagues? You need a version of your book! Let's try and do that! Later on, you'll probably want to merge your newest version back into the original book. That's what we'll do in [](./005.md). -Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online? +> Can you make a new branch of your book with an additional file `file_on_new_version.md` and view it online? 1. Add a new Issue to let people know you're working on something by going to your repository (`https://github.com//`) - {octicon}`issue-opened;1em` `Issues` - `New issue` (note that is not required for making your own version, but it's good practice so that people know where you're working on) 2. Add a title and description, eg. `Added some content` -3. On `Assignees`, click `Assign yourself +3. On `Assignees`, click `Assign yourself` to make clear that you feel responsible for this issue. 4. Click `Submit new issue` 5. In the new window, under `Development`, click `Create a branch` (note that you could also make branches in other ways, but in this way it's directly linked to the issue). A 'branch' is a separate version of the book which keeps the link with the original book. 6. Use the default options and click `Create branch` diff --git a/book/exercises/005.md b/book/exercises/005.md new file mode 100644 index 0000000..40c8375 --- /dev/null +++ b/book/exercises/005.md @@ -0,0 +1,28 @@ +# Exercise 5: Merge your version in the original book + +In [](./004.md) you created your own version of a book. But it would be a pity if you never contribute back to the original book right? Probably your additions are very useful there too! You'll merge you version of the book which is stored on a branch into the original book which is on main. If there've been some changes on that main branch in the meantime, git will take care of that! + +> Can you merge your branch into `main` with a pull request? + +1. Go to your repository homepage (`https://github.com//`). Probably, it will have big yellow announcement saying {octicon}`git-branch;1em` `1- had recent pushes minutes ago - Compare & Pull request`. We'll ignore that for now and do it manually. +2. Go to the pull request page on your repository homepage (`https://github.com//`) - {octicon}`git-pull-request;1em` and click `New pull request` +3. On {octicon}`git-compare;1em` make sure you point from your branch `1-` into `main`. So, `main` on the left, {octicon}`arrow-left;1em` and `1-` on the right. Main is the default name for the branch which has the most recent/stable version. The page should now show all the changes you made on the `1-`-branch. If there would be changes on the `main` branch in the meantime, they should show up here too. +4. Click `Create pull request` to start the process of moving your changes into the `main` branch. If there were changes on both branches which are conflicting, it will tell you there's a merge conflict. If you followed the steps until now, that shouldn't be the case. Solving those merge conflicts is topic for another exercise. +5. Add a title and description described the changes you made. This is done to give other people a summary of what has been changed. +6. Assign yourself to make clear that you feel responsible. +7. Click `Create pull request`. On the next page you'll see that GitHub gives an announcement {octicon}`bookmark;1em` ` linked an issue now that may be closed by this pull request`. That sounds useful! +8. As you're the only one in this repo there's nobody to review your work. So let's continue and merge your changes into `main` by clicking `Merge pull request` and `Confirm merge` (eventually specifying the suggested commit message and description) +9. As this issue is now closed, you can safely remove the branch `1-` as you don't need it anymore. You can do so by clicking `Delete branch`. +10. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Merge pull request #2 from /1- / the commit message of the commit you just made` - Wait for it to finish - In the summary, click the link of the main branch or the primary book at root. +11. Do you see your change from your branch 1-? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page. Check that the url indeed shows that you're on main. + +```{admonition} Check your understanding +:class: note + +Before moving on to the next exercise, make sure you understand the following: +- What is the purpose of creating a pull request? +- How do you manually create a pull request on GitHub? +- Why is it important to add a title and description to your pull request? +- What is the final step after merging your pull request? +- How can you verify that your changes have been successfully merged into the main branch? +``` \ No newline at end of file