Exercise 1: First file edit

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.

  1. Go to the the file book/intro.md on your GitHub repository (https://github.com/<your_username>/<your_repo_name>) - Code - Book - intro.md - Edit this file

  2. Add some text. Feeling brave? Have a look at the MyST cheat sheet. 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 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+F5to 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

https://github.com/TeachBooks/template_figures/blob/main/excercise1.gif?raw=true

Fig. 1 Demonstration of all steps of this exercise, video available here#

Check your understanding

Where are the contents of the book stored?

 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! 🐍

Show answer(s)

Try again

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! 🐍

 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! 🐍

Show answer(s)

Try again

You can determine the URL of the book website for a specific GitHub repository by checking the repository’s settings under GitHub Pages.

 True

Correct!

 False

Incorrect.

Show answer(s)

Try again

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. 🐍

 By visiting the book’s website URL after the GitHub Actions workflow has completed.

Hissstory made! Great job! 🐍

Show answer(s)

Try again

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.

 False

Exactly, well-written commit messages improve project maintainability and make it easier to revert changes if necessary also for solo authors.

Show answer(s)

Try again