From 4dda1b0e95e93ba05e01bd3213cb82cfae8003ba Mon Sep 17 00:00:00 2001 From: Katia Gatt Date: Tue, 13 May 2025 09:20:57 +0200 Subject: [PATCH] exercise 6 --- book/exercises/006.md | 112 +++++++++++++++++++++++++----------------- book/exercises/007.md | 53 ++++++++++++++++++++ 2 files changed, 119 insertions(+), 46 deletions(-) create mode 100644 book/exercises/007.md diff --git a/book/exercises/006.md b/book/exercises/006.md index 9287d06..3dda89f 100644 --- a/book/exercises/006.md +++ b/book/exercises/006.md @@ -1,53 +1,73 @@ -# Exercise 6: Contribute to the book of somebody else +# Exercise 6: Use pages from someone else's book + +So far, you've been working inside your own book. But what if someone else has already written a page that you'd like to reuse or refer to in your own book? Instead of copying the content manually, you can **link to their page directly** using [TeachBooks’ external content feature](https://teachbooks.io/manual/features/external_toc.html). This way, if the original page is updated, your book will reflect those changes automatically! + +\::::::{topic} Exercise objective +Can you include a page from someone else’s book into your own using the `external` keyword? +\:::::: + +1. Choose a book you want to reuse content from. For this exercise, you can use this one as an example: `https://github.com/TeachBooks/manual`. Browse its content to find a specific page (e.g. `intro.md`). +2. In your own book repository, open the `_toc.yml` file. This controls which pages are shown in your book and in what order. +3. To use the functionality, use the `external:` keyword in the `_toc.yml` file to include a file directly from the GitHub repository as follows: + +```yaml +format: jb-book +root: . + +parts: + - caption: ... + chapters: + - file: ... + . + . + . + - external: + . + . + . +``` + +4. Try out different kind of links. You can point to: +* A file on a branch (this pulls the most recent version on that branch): `external: https://github.com/TeachBooks/manual/blob/release/book/intro.md` +* A file at a specific commit (this takes the file during the state of a specific commit (06d67e8)): `external: https://github.com/TeachBooks/manual/blob/06d67e8a0110c94d9147ce07090656dedc7d0e64/README.md` +* A file from a tag (this locks the file to the version associated with a specific tag (v1.1.1)): `external: https://github.com/TeachBooks/manual/blob/v1.1.1/README.md` + + +5. Commit your changes and push them to your GitHub repository. +6. Open the book online (e.g. via GitHub Pages or the link in your repository's `Actions` > latest deploy) and check whether the external page appears correctly. +7. If the external page doesn't load or gives an error, double-check: + + * The link is a raw `.md` file on GitHub (not the preview or rendered page). + * You’ve committed and pushed the `_toc.yml` change. + + +\`\`\`{admonition} Example `_toc.yml` snippet + +```yaml +format: jb-book +root: intro + +chapters: + - file: 001 + - file: 002 + - external: + url: https://github.com/teachbooks-demos/book-collaboration/blob/main/004.md + title: Collaboration in GitHub + - file: 003 +``` + +```` ```{tip} -For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner. -``` - -So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. - -```{note} -The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. -``` - -::::::{topic} Exercise objective -Can you fork a book repository of someone else, make changes and contribute back? -:::::: - -```{tip} -This part describes how you can make a change in the book of someone else. -``` - -1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). -2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. -3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` -4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ -5. Check the changes in the online book. -6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. -7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. -8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. -9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. -10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! - -```{tip} -This part describes how you can accept the changes in your book made by someone else. -``` - -1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. -2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? -3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. -4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. -5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. - -Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. +You can use external pages from public GitHub repositories that are formatted as valid Markdown. Just remember: the content is *read-only*—you can’t directly edit the external page from your book! +```` ```{admonition} Check your understanding :class: note Before moving on, make sure you understand the following: -- What is a fork and how does it differ from a branch? -- Why is it important to create an issue before starting to work on a contribution? -- How do you create a pull request from a forked repository to the original repository? -- What should you include in the description of a pull request? -- How can you ensure that your friend is aware of your pull request? -``` \ No newline at end of file +- What is the difference between linking to an external page vs copying it into your own book? +- How do you use the `external:` keyword in `_toc.yml`? +- Why might it be useful to include a page from another book instead of rewriting it yourself? +- How can you make sure an external page link works properly? +``` diff --git a/book/exercises/007.md b/book/exercises/007.md new file mode 100644 index 0000000..94d9635 --- /dev/null +++ b/book/exercises/007.md @@ -0,0 +1,53 @@ +# Exercise 7: Contribute to the book of somebody else + +```{tip} +For this exercise you will need a partner, as well as your own book. In the first part, each of you will make a change in the book of the other, then request the other to review and merge the change. In the second part, you will go back to your book and accept the change made by your partner. +``` + +So far you did everything on your own, within a single repository. However, book-editing would be really boring if it would always be like that. Let's team up with someone to see the potential of collaborative book editing using Git! In this exercise you will take the book of someone else and create your own version of that one. However, unlike a previous exercise, we cannot simply make a branch, because you don't have _access_ to their repository. However, you can make a copy of the repository on your own account and make some changes there. Then, you can send that back to your friend's repository and see if they would like to incorporate your changes. The repository you create (your own version) is called a **fork**. + +```{note} +The fork-pull request workflow is very common in open-source projects. It allows people to work independently without asking for access or worrying about affecting the original source code, as well as give the original author of the code a clear way to review the changes and decide if they want to include them in the original repository. +``` + +::::::{topic} Exercise objective +Can you fork a book repository of someone else, make changes and contribute back? +:::::: + +```{tip} +This part describes how you can make a change in the book of someone else. +``` + +1. Go to the repository to which you want to contribute (`https://github.com//`), then add an issue to let people know you're working on something - {octicon}`issue-opened;1em` `Issues` - `New issue`. You did this in [](./004.md). +2. Go back to the home page of repository to which you want to contribute (`https://github.com//`) and click {octicon}`repo-forked;1em``Fork` at the top right corner to create a copy of the repository under your GitHub account. +3. Choose yourself as an owner and click `Create fork`. In the new screen you should see the same repo but on your own account. Furthermore, it mentions `forked from /` +4. Make some changes on the main branch of your forked repo. *Make sure you make changes to something in the book subdirectory!_ +5. Check the changes in the online book. +6. Go to the pull request page on your forked repository homepage (`https://github.com///pulls`) - {octicon}`git-pull-request;1em` and click `New pull request`. +7. On {octicon}`git-compare;1em` make sure you point from your repositories branch `head repository: /:compare: main` into the original repository `base repository: / base:main`. This should be the case by default. +8. In the description, add some explanation which for your friend to understand what your changes includes. Furthermore, it's useful to add `Closes #` so that the pull request is linked to the issue. +9. Click `Create pull request`. On the next page you'll see that the pull request is created in your friends repository. +10. Your friend will get a notification, but it wouldn't hurt to ask the person to review your pull request. Your friend might have some feedback or will just accept it right away! + +```{tip} +This part describes how you can accept the changes in your book made by someone else. +``` + +1. First, how can you tell someone has made a pull request from a fork into your repository? One way is to check your GitHub notifications, which you can find most easily by clicking on the inbox icon in the top right corner of [github.com](https://github.com). You can also find this by going to your repository and clicking on {octicon}`git-pull-request;1em` `Pull requests`. +2. Once on the pull request page, you should see that something is listed there. Click on it and read what it says. Just as in a previous exericse, you should see some notes from the Pull Request creator, as well as a summary of the commits, and a tab to view "Files changed." Can you identify how you can tell whether or not this is from a forked repository? +3. At the top of the page, next to the status icon (which should say "Open" in green), look for the summary. It should say "`` wants to merge x commit(s) into ``:`main` from ``:`main`. Where in each case `main` is the branch, and the usernames before the `:` symbol indicate the owner of the repository; because the merge is coming from your friend's repository, it is obvious that it is a fork. +4. Review the change from your friend. Note that if this were a "real" project, you may want to use some of the useful GitHub collaboration features, for example: adding comments in the conversation tab, commenting on specific lines of code, requesting changes, or making additional commits to the pull request yourself. However, for this exercise, you can simply click `Merge pull request` if you are happy with the changes. +5. Once the merge is complete, check that the book is updated via the Actions tab, and visit the page to check that the changes are there. + +Now that the changes have been successfully incorporated, you should have seen that both Pull Requests (one in your book repo, the other in your forked repo) have been completed. Unless you want to continue collaborating in the future, you can delete your forked repository. + +```{admonition} Check your understanding +:class: note + +Before moving on, make sure you understand the following: +- What is a fork and how does it differ from a branch? +- Why is it important to create an issue before starting to work on a contribution? +- How do you create a pull request from a forked repository to the original repository? +- What should you include in the description of a pull request? +- How can you ensure that your friend is aware of your pull request? +``` \ No newline at end of file