Merge pull request #37 from TeachBooks/exercises

Exercises for workshop

README.md

@@ -20,7 +20,7 @@ Video available [here](https://youtu.be/nN3Oi_MVvF0)
 
 ![Create new repository](figures/create_new_repository.png)
 
-3. You can choose for `Private` only if you've GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server. Otherwise, you won't be able to publish your TeachBook online.
+3. You can choose for `Private` only if you've GitHub Pro, GitHub Team, GitHub Enterprise Cloud, or GitHub Enterprise Server. Otherwise, you won't be able to publish your TeachBook online. Furthermore, it prevents people from contributing to your book, making your book essentially 'closed' instead of 'open.
 
 4. (Only required for private repositories:) Create a Personal Access Token (classic) with at least the scopes `repo`, `read:org` and `gist` as described in the [github documentation](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens), and add this token with the name `GH_PAT` as a `Repository secret` or `Organization secret` (`Settings` > `Secrets and variables` > `Actions` > `Repository secrets` or `Organization secrets`).
 

book/_config.yml

@@ -1,4 +1,3 @@
-title: Template
 author: TeachBooks Team, built with <a href="https://teachbooks.io">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a> #add your own name here
 
 execute:

book/_toc.yml

@@ -7,6 +7,14 @@ parts:
     - file: some_content/overview.md
       sections:
       - file: some_content/text_and_code.ipynb
+    - file: exercises/exercises
+      sections:
+      - file: exercises/001.md
+      - file: exercises/002.md
+      - file: exercises/003.md
+      - file: exercises/004.md
+      - file: exercises/005.md
+      - file: exercises/006.md
     - file: references.md
     - file: changelog.md
     - file: credits.md

book/exercises/001.md

@@ -0,0 +1,26 @@
+# Exercise 1: First file edit
+
+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?
+
+1. Go to the the file `book/intro.md` on your GitHub repository (`https://github.com/<your_username>/<your_repo_name>`) - {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!
+3. Click `Commit changes`
+4. Add a message and description of your change. With this `commit` you save your changes to the git-timeline. Any commit can always be reverted. Therefore, it's useful to shortly explain what is included in your commit. Later on, you'll make commits which may contain changes to many different files. In that case, a descriptive commit message and description is even more useful!
+5. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one)
+6. Click `Commit changes`.
+7. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update intro.md / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root`
+8. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page (your browser keeps a cached version of website you recently visit, but we actually want the most up-to-date version!).
+
+```{admonition} Check your understanding
+:class: note
+
+Before moving on to the next exercise, make sure you understand the following:
+- Where are the contents of the book stored?
+- How can you edit a single file via the GitHub browser interface?
+- What is a commit and what role does it play in the editing process?
+- Given a specific GitHub repository, can you determine the URL of the book website?
+- How can you view the changes you made to the book?
+- What is the purpose of a commit message and description?
+```

book/exercises/002.md

@@ -0,0 +1,54 @@
+# Exercise 2: Add a new file to the table of contents
+
+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?
+
+1. Go to the (`https://github.com/<your_username>/<your_repo_name>`) - {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/<your_username>/<your_repo_name>`) - {octicon}`code;1em` `Code` - `Book` - `_toc.yml` - {octicon}`pencil;1em` `Edit this file`
+3. Add `file_to_be_added_to_toc.md` as a second item in the `Some content` chapter
+
+````{admonition} Need some help?
+:class: tip, dropdown
+Your `_toc.yml` should look like
+```yaml
+format: jb-book
+root: intro.md
+
+parts:
+  - caption: Contents
+    chapters:
+    - file: some_content/overview.md
+      sections:
+      - file: some_content/text_and_code.ipynb
+      - file: file_to_be_added_to_toc.md
+    - file: exercises/exercises
+      sections:
+      - file: exercises/001.md
+      - file: exercises/002.md
+      - file: exercises/003.md
+      - file: exercises/004.md
+      - file: exercises/005.md
+      - file: exercises/006.md
+    - file: references.md
+    - file: changelog.md
+    - file: credits.md
+```
+````
+4. Click `Commit changes`
+5. Add a message and description of your change
+6. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one)
+7. Click `Commit changes`
+8. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root` (getting bored of waiting? There'll be exercising on doing this locally which prevents you from waiting)
+9. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
+
+```{admonition} Check your understanding
+:class: note
+
+Before moving on to the next exercise, make sure you understand the following:
+- Are all files in the repository added to the website?
+- What is the purpose of the `_toc.yml` file?
+- What happens if a file is not listed in the `_toc.yml`?
+- How can you verify that your changes to `_toc.yml` were successful?
+- Does the structure of the `_toc.yml` file need to match the directory structure of the repository?
+```

book/exercises/003.md

@@ -0,0 +1,46 @@
+# Exercise 3: Change book configuration
+
+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?
+
+1. Go to the the file `book/_config.yml` on your GitHub repository (`https://github.com/<your_username>/<your_repo_name>`) - {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.
+````{admonition} Need some help?
+:class: tip, dropdown
+The first line of your `_config.yml` should look like
+```yaml
+author: <your_name>, built with <a href="https://teachbooks.io">TeachBooks</a> and <a href="https://jupyterbook.org/">Jupyter Book</a>, <a href="https://creativecommons.org/licenses/by/4.0/" target="_blank" rel="license noopener noreferrer"">CC BY 4.0<img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/cc.svg" alt=""><img style="height:22px!important;margin-left:3px;vertical-align:text-bottom;" src="https://mirrors.creativecommons.org/presskit/icons/by.svg" alt=""></a>
+```
+````
+3. In the `Edit` field, change the title of your homepage which will under the logo and above the table of contents
+````{admonition} Need some help?
+:class: tip, dropdown
+The 21st line of your `_config.yml` should look like
+```yaml
+        text: <your_title>
+```
+````
+4. In the `Edit` field, change the repository url which will be used to allow other people to open your repository, suggest edits and open issues as shown in top right corner of the built book under {octicon}`mark-github;1em`.
+````{admonition} Need some help?
+:class: tip, dropdown
+The 24th line of your `_config.yml` should look like
+```yaml
+      repository_url: "https://github.com/<your_username>/<your_repository>"
+```
+````
+5. Click `Commit changes`
+6. Add a message and description of your change
+7. Select `Commit directly to the main branch` (this adds your change your change to the default version instead of making a new one)
+8. Click `Commit changes`
+9. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _config.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, click on the link of your book shown in the table `Branches deployed` and under `Primary book at root`
+10. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
+
+```{admonition} Check your understanding
+:class: note
+
+Before moving on to the next exercise, make sure you understand the following:
+- What is this special `_config.yml` file?
+- Changes in `_config.yml` can have effect on multiple pages in the book
+- The `_config.yml` is generally not used for adding content
+```

book/exercises/004.md

@@ -0,0 +1,26 @@
+# Exercise 4: _Your_ Version of the Book
+
+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?
+
+1. Add a new Issue to let people know you're working on something by going to your repository (`https://github.com/<your_username>/<your_repo_name>`) - {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` 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`
+7. Ignore the `checkout in your local repository`- popup for now (later on you'll know what this is and how to use it)
+8. Go to `Code` - {octicon}`git-branch;1em` `main` and click on `1-<your_issue_title>` to open your branch.
+9. Add a book page as explained in [](./002.md) and make sure you commit to the  `1-<your_issue_title>`-branch.
+10. Go to {octicon}`play;1em` `Actions` - The most recent workflow run `Update _toc.yml / the commit message of the commit you just made` - Wait for it to finish - In the summary, you should now see multiple Branches. Click on the link of your new branch ``1-<your_issue_title>`
+11. Do you see your change? If you don't see it click `CTRL`+`F5`/`Control`+`F5`to refresh the page.
+
+```{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 new branch in your repository?
+- Why is it good practice to create an issue before starting work on a new feature or change?
+- How can you view the changes made in your new branch online?
+```

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/<your_username>/<your_repo_name>`). Probably, it will have big yellow announcement saying {octicon}`git-branch;1em` `1-<your_issue_title> had recent pushes <some> 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/<your_username>/<your_repo_name>`) - {octicon}`git-pull-request;1em` and click `New pull request`
+3. On {octicon}`git-compare;1em` make sure you point from your branch `1-<your_issue_title>` into `main`. So, `main` on the left, {octicon}`arrow-left;1em`, and `1-<your_issue_title>` 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-<your_issue_title>`-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` `<your_username> 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-<your_issue_title>` 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 <your_username>/1-<your_issue_title> / 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-<your_issue_title>? 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?
+```