mirror of
https://github.com/TeachBooks/template.git
synced 2026-11-12 22:25:52 +00:00
125 lines
4.8 KiB
Markdown
125 lines
4.8 KiB
Markdown
(exercise_1)=
|
||
# 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.
|
||
|
||
::::::{topic} Exercise objective
|
||
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/v1/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!).
|
||
|
||
````{hint} Watch the steps in action below
|
||
class: dropdown
|
||
|
||
```{figure} https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true
|
||
---
|
||
name: template_demo_public
|
||
---
|
||
Demonstration of all steps of this exercise, video available [here](https://youtu.be/gn1zBmmunco)
|
||
```
|
||
````
|
||
|
||
:::::{card} Check your understanding
|
||
|
||
::::{question}
|
||
:type: multiple-choice
|
||
:variant: single-select
|
||
:showanswer:
|
||
:nocaption:
|
||
:columns: 1
|
||
|
||
Where are the contents of the book stored?
|
||
---
|
||
[x] In a GitHub repository, typically organised into directories with markdown and Notebook files
|
||
> Fang-tasssstic 🐍
|
||
[ ] On the official Teachbooks website
|
||
> Slither back and try again! 🐍
|
||
[ ] In a local folder on your computer only
|
||
> Slither back and try again! 🐍
|
||
---
|
||
|
||
::::
|
||
|
||
::::{question}
|
||
:type: multiple-choice
|
||
:variant: single-select
|
||
:showanswer:
|
||
:nocaption:
|
||
:columns: 1
|
||
|
||
What is a commit and what role does it play in the editing process?
|
||
---
|
||
[ ] A commit automatically publishes changes to a live website without the need for approval
|
||
> Keep ssslithering... you’ll get it! 🐍
|
||
[ ] A commit is like a magic "undo" button that erases all your mistakes without anyone ever knowing they happened
|
||
> Keep ssslithering... you’ll get it! 🐍
|
||
[x] A commit is a snapshot of changes made to files in a repository, allowing tracking of modifications and collaboration
|
||
> Ssssuper job! 🐍
|
||
[ ] A commit is a way to permanently delete changes from a repository to prevent errors
|
||
> Keep ssslithering... you’ll get it! 🐍
|
||
---
|
||
|
||
::::
|
||
|
||
::::{question}
|
||
:type: multiple-choice
|
||
:variant: single-select
|
||
:showanswer:
|
||
:nocaption:
|
||
:columns: 2
|
||
|
||
You can determine the URL of the book website for a specific GitHub repository by checking the repository’s settings under GitHub Pages.
|
||
---
|
||
[x] True
|
||
[ ] False
|
||
---
|
||
|
||
::::
|
||
|
||
::::{question}
|
||
:type: multiple-choice
|
||
:variant: single-select
|
||
:showanswer:
|
||
:nocaption:
|
||
:columns: 1
|
||
|
||
How can you view the changes you made to the book?
|
||
---
|
||
[ ] By running the command git show-book in the terminal.
|
||
> Ssssstrike missed! Try again. 🐍
|
||
[ ] By refreshing the repository page and hoping the changes appear immediately.
|
||
> Ssssstrike missed! Try again. 🐍
|
||
[ ] By checking the "Commits" tab in the GitHub repository to see a visual preview of the book.
|
||
> Ssssstrike missed! Try again. 🐍
|
||
[x] By visiting the book's website URL after the GitHub Actions workflow has completed.
|
||
> Hissstory made! Great job! 🐍
|
||
---
|
||
|
||
::::
|
||
|
||
::::{question}
|
||
:type: multiple-choice
|
||
:variant: single-select
|
||
:showanswer:
|
||
:nocaption:
|
||
:columns: 2
|
||
|
||
A commit message and description are only necessary when collaborating with others on a Git-based book project; solo authors do not benefit from writing detailed commit messages.
|
||
---
|
||
[ ] True
|
||
> Commit messages and descriptions are crucial for providing context about changes, making it easier to understand why a change was made, not just what was changed. They help developers (including your future self) track progress, collaborate effectively, and debug issues efficiently.
|
||
[x] False
|
||
> Exactly, well-written commit messages improve project maintainability and make it easier to revert changes if necessary also for solo authors.
|
||
---
|
||
|
||
::::
|
||
|
||
:::::
|