Instructor notes
Pre-flight checklist, timing, failure modes, and the dated UI verification log.
Pre-flight checklist
One week before
- Check the date and the room in the KSL course entry.
- Check the enrolment list. The instructor expects mostly DH Major students; prepare the Minor and elective caveat (U-03).
- Send the Setup page to the participants. Ask the command-line learners to complete Prepare the command line before the session.
The day before
- Run X1 to X6 in a fresh test account or a fresh repository. Compare each step with the UI verification log.
- Run the Command line tabs of X1 to X6 in a private throwaway repository. Compare each step with the command-line verification log. Delete the repository and the Project afterwards.
- Update a screenshot if the interface changed. Run
npm run screenshots:annotate. - Check that the showcase Project is public and linked to the course repository.
- Check githubstatus.com.
On the day
- Open the slides, the showcase Project, and the example repository in separate tabs.
- Write the Wi-Fi details and the site URL on the board.
Timing
| Block | Planned | Risk | Cut if late |
|---|---|---|---|
| Frame | 15 min | Discussion runs long | Show the comparison table of the approaches only; skip the discussion |
| X1 | 25 min | Account creation, two-factor authentication | Pair learners without an account |
| X2 | 35 min | Deriving E01-T1 takes long | Give five minutes for E01-T1, then compare with the backlog; E08 can move to X3 |
| X3 | 40 min | Linking, visibility, and dates take time | Skip the second dependency and the M2 justification; add them in X6 |
| X4 | 35 min | Merge conflicts, review rights | Self-review with Comment |
| X5 | 35 min | Upload, rename | Skip the citation file; use the recovery package instead of the release |
| X6 | 25 min | The option discussion runs long | Skip the export and the status update; keep the decision record and the dates |
| Transfer and exit | 10 min | — | Exit check in pairs |
Known failure modes
| Symptom | Cause | Response |
|---|---|---|
| Red cross and e-mails after X1 | The template workflows run on the first commit and fail at the Pages deployment (404) and the link check | Expected. Show Settings → Actions → General → Disable actions. |
| Copilot fills in commit messages and requests reviews | Account settings of the learner | Use it as an example: read and replace AI text. A Copilot review can fail with a quota message. |
| Workflows show error icons | Status options renamed after the Project was created | Edit the workflows and select an existing option. |
| Roadmap settings lost | The confirmation dialog after Save view was not confirmed | Repeat and confirm with Save. |
CITATION.cff shows the template |
The template ships its own citation file | X5 corrects it. |
| A learner commits real data | — | Stop, remove the file, and explain that the history keeps it. For real data, the repository must be deleted or cleaned. Prevention: synthetic data only. |
Teaching points
- Rules versus plans. KSL governs this course, not the thesis. Thesis rules come from the study plan and the faculty regulations, and they differ per programme.
- Hierarchy versus dependency. Parent-child means “part of”; blocked-by means “waits for”.
- Milestone versus date field. A milestone groups work under a due date in the repository; date fields schedule each item in the Project.
- Release versus deposit. A GitHub release is not preservation. A DOI comes from a repository such as Zenodo, and only after an explicit decision.
- What GitHub cannot guarantee: quality, deadline compliance, confidentiality, and long-term preservation.
UI verification log
The instructor checked each element below on 12 October 2026 in Google Chrome on macOS, signed in to a personal GitHub account. “API” means that the step was created with the GitHub CLI or API, and that the result was checked in the interface. “Docs” means that the label follows the official documentation and was not clicked in the test. Check every “API” and “Docs” row on the day before the session.
| Exercise | Element | How checked | Observation |
|---|---|---|---|
| X1 | Template link opens “Create a new repository” with the template preselected | UI | Sections “1 General”, “2 Configuration”, “3 Jumpstart your project with Copilot (optional)” |
| X1 | Template workflows on the first commit | UI and API | “Render and Publish” fails at Deploy (Pages not enabled, 404); “Link Check” fails; “Create changelog” succeeds |
| X1 | Web editor and commit dialog | UI | Copilot pre-fills message and description; options “Commit directly to the main branch” and “Create a new branch for this commit and start a pull request” |
| X1 | Visibility | UI | Settings → General → Danger Zone → “Change repository visibility” |
| X1 | Disable Actions | UI (menu) and API (change) | Settings → Actions → General → “Disable actions” |
| X2 | Labels, Issues, sub-issues | API | Native sub-issues show as panel “Sub-issues” with “Create sub-issue”; pills “Parent” and “Blocked by” under the title |
| X2 | “Create sub-issue” and “Add existing issue” | UI (12 Oct, throwaway repository) | The button Create sub-issue appears below the description after the page loads. Its arrow menu has Create sub-issue and Add existing issue. Adding an existing issue shows the panel “Sub-issues” |
| X3 | Milestones | API | Milestones page with due dates and descriptions |
| X3 | Project creation from the repository tab, “New project” | Docs | The button “New project” and “Link a project” were seen on the Projects tab; creation itself was done by API |
| X3 | Fields and Status options | API | Status options replaced; fields Priority, Basis, Start date, Target date |
| X3 | Views | API (create) and UI (roadmap) | Roadmap date fields, zoom, and markers need the UI; Save view asks for confirmation |
| X3 | Built-in workflows | UI | Six active after repair, including “Item added to project → Backlog” and “Pull request linked to issue → In review” |
| X3 | “Make a copy” of a Project | UI (12 Oct) | Project menu … → Make a copy. The dialog says: views, custom fields, insights, and workflows are copied; issues and pull requests are not. The owner must be selected. The copy starts private. The Status options and the fields Priority, Start date, Target date, and Basis are copied |
| X3 | Workflows in the copy | UI and API (12 Oct) | Six workflows stay on, including “Auto-add sub-issues to project” and “Pull request linked to issue → In review”. “Auto-add to project” is off. Adding an epic to the copy also added its sub-issue with Status Backlog |
| X3 | Link a Project to a repository | UI (12 Oct) | Repository Projects tab → Link a project → select the Project → Save |
| X3 | Project visibility and access | UI (12 Oct) | … → Settings → Danger zone → Visibility. Manage access → Invite collaborators, default role Write. Nobody was invited in the test |
| X3 | “Mark as blocked by” in Relationships | UI (12 Oct) | Gear icon next to Relationships → Mark as blocked by → select the issue → close the list. The pill “Blocked by” appears under the title |
| X4 | Pull request flow | API (create, merge) and UI (pages) | Status moved to “In review” on link and “Done” on merge; Issue “closed this as completed in #43” |
| X5 | Upload and rename in the browser | Docs | Files were added by API |
| X5 | Release page | API (create) and UI (page) | Release “Latest” with notes and source archives |
| X6 | Status update | API (create) and UI (panel) | Header badge “On track”; panel “Status updates” with “Add update” |
| X6 | “Export view data” | UI (menu, 12 Oct) | Only in the arrow menu of the view tab, not in the View button (the documentation says otherwise). The documentation states a .tsv file; the download was not run |
| All | Private path | API and UI | Private repository and private Project; sub-issues, dependencies, milestones, and status updates work the same way |
Command-line verification log
The instructor ran every Command line tab of X1 to X6 on 13 October 2026 in zsh on macOS, with gh 2.102.0 and git 2.54.0. The run used a private throwaway repository and a private copy of the showcase Project. A second run on the same day, with the same versions, tested the commands that changed after the review of pull request #16. It created the Issues in another order than X2: an extra Issue first, then E08, then E01. Windows and Git Bash were not tested.
| Exercise | Command | Observation |
|---|---|---|
| X1 | gh repo create … --template … --clone |
The clone contains the template files at once. |
| X1 | gh api -X PUT …/actions/permissions -F enabled=false |
The read-back showed true for a few seconds, then false. |
| X2 | gh issue view … --json body --jq .body \| gh issue create … --body-file - |
The bodies of the example Issues are identical to backlog.yml. In a new repository, E01 is #1 and E08 is #2. |
| X2 | gh issue create --parent |
gh issue view lists the sub-issues and their progress. |
| X3 | gh api …/milestones -f due_on=… |
On creation, T00:00:00Z stored the day before, for example 2027-05-31 for 2027-06-01. T12:00:00Z stored the right day. A change with -X PATCH stored the right day with both times. |
| X3 | Helper issue, with the Issues in another order |
Each lookup returned the right number, also for an Issue created one command before. A partial ID such as E0 returned nothing. |
| X3 | gh project copy |
In a terminal, gh prints the address of the copy. The copy starts private. |
| X3 | gh project link N with --owner @me |
Failed in three forms. With --repo NAME and without --repo: “Could not resolve to a Repository with the name ‘@me/…’”. With --repo OWNER/NAME: “has different owner from ‘@me’”. gh project link N without flags, in the folder of the repository, worked. |
| X3 | gh issue edit … --add-project for the two epics |
With both epics in one command, the second failed with “created a temporary conflict”. One Issue per command worked. The workflow added the six sub-issues with Status Backlog after about 70 seconds. In the first run, gh project item-add took less than ten seconds. |
| X3 | gh issue edit --add-blocked-by |
gh issue view shows the line blocked-by. |
| X4 | gh issue develop --name … --checkout, gh pr create |
The Status changed to In review. In the second run, it still showed Backlog after 6 seconds and In review after 18 seconds. |
| X4 | gh pr merge --merge --delete-branch |
gh switched the folder to main and pulled. The Issue closed as completed, and the Status changed to Done. |
| X5 | gh api …/contents/… -H "Accept: application/vnd.github.raw", git add |
The file has the same content as the CSV of the course repository. git warns that LF will be replaced by CRLF, because the template sets this line ending for CSV files. |
| X5 | git commit -m … -m "Closes #7" on main |
The push closed the Issue as completed. |
| X5 | gh release create, gh issue close --comment |
Release and closed Issue as expected. In the second run, gh release view --json url put the address of the release into the comment. |
| X6 | gh issue create --parent … --milestone … --blocked-by … |
One command sets the parent, the milestone, and the dependency. The workflow added the new sub-issues to the Project. |
| X6 | gh api -X PATCH …/milestones/2 |
The due date of M2 changed and changed back. |
| X6 | gh project item-list --format json |
The file lists every item with its Status. A field without a value is not in the file. gh does not apply the filter of a view. |
| All | Project fields, workflows, access, status update | No gh command, or a command that needs internal IDs (field values). The exercises mark these steps Browser only. |