Repository setup

Best practices and resources for setting up teaching repositories.

Goals: efficiency (clear principles, automation, git-based improvement cycle, sharing/publication-readiness)

Repositories

Course Materials Repository Exams Repository
ABD Analytics and Big Data repository repository
ITSecM IT Security Management repository repository
MLBD Machine Learning for Big Data repository β€”
Prog Introduction to Programming repository β€”
IDW Introduction to Digital Work repository repository
OSP Open Source Project repository β€”
LRSem Literature Review Seminar repository β€”
Theses Theses repository β€”

General setup principles

Repository

  • We use Quarto for teaching repositories.
  • Each course has a separate repository and page.
  • Each course is hosted publicly on GitHub.
  • Each course can be used locally and offline.
  • Shared materials may be extracted in the shared-materials repository and included through git submodules and quarto include commands.
  • Add branch protection rule for main: restrict deletions and block force pushes
  • Teaching contents are licensed under the CC-BY license per default.
  • Zenodo/DOI

Files and directories

  • Overview of related courses in the README.md file (see other courses here).
  • A syllabus (example)
  • Detailed teaching notes allow teaching assistants to replicate it quickly.
  • One slide-deck (optional notebook) per session (no multi-session slide decks)
  • Markers on the slides indicate where in-class exercises are used
  • Markers on the slides include explicit discussion prompts
  • Markers on the slides indicate key concepts (must learn vs. learning notes on optional contents)
  • HTML and PDF versions are automatically generated (e.g., GitHub actions).
  • All files: Each sentence should be in a new line
  • Dates, rooms, and links should be in one place to prevent inconsistent information.
  • slides dir for session slides (one per session)
  • notes dir for teaching notes (one per session)
  • exercises dir for exercises (one per session; with assignment/solution rendering - TBD: including in-class exercises?)
  • images: tbd.
  • README.md
  • index.qmd
  • syllabus.qmd
  • teaching_notes.qmd
  • feedback.qmd (feedback and improvements with links to commits/PRs and issues, regular process to collect issues etc.)
  • Makefile
  • references.bib
  • _quarto.yml
  • Optional: news.qmd, pyproject.toml, assignment.qmd or group_work.qmd
  • TBD: objectives.qmd, preparation.qmd, _quarto-pdf.yml, variables.qmd, data dir, scripts dir?

Commands

  • PDFs should be generated through make pdfs (a make -> quarto render -> decktape chain, as in ABD).
  • gh-actions: …
  • links, spellchecking, pdf generation

Page

  • Links related to continuous improvement: feedback, evaluations, improvement.
  • Logo, navigation on the left, …
  • LMS links never point to a specific course but to a search in the LMS (e.g., for the project).
  • Badges??

Automated checks/report:

  • Start with the LLM version (simply pass all principles - maybe even as a chatgpt/codex prompt)?
  • iterate over repos locally
  • rule-based and llm-based checks (llm: optional/additional)
  • pass/fail with detailed report
  • Surveys to collect feedback for individual sessions (Google Forms?)
  • Options to provide feedback should be linked on the first page.
  • Session pages. One page per teaching session, integrating video, slides, exercise materials, code/notebooks, quizzes, and follow-up resources. (see example)
  • Resource index. One cross-session page that makes all materials findable by topic, concept, method, or material type (see example).

New repository

Use teaching-repository-template to create a new repository from the template.

TODO:

  • codex: create template repository (based on latest…)
  • use codex to compare template repo with latest teaching and update before using it as a basis

https://chatgpt.com/c/6a4dff3d-3ad8-83eb-81ad-ba0418a6752e

@GitHub I would like to create a template for teaching repositories (lectures, ...). best practices are still evolving. the latest version of a repo is in https://github.com/fs-ise/analytics-and-big-data .  also, a lot of best practices and ideas for principles are documented in https://fs-ise.github.io/handbook/teaching/materials.html . also, I like the progress indicators in https://github.com/fs-ise/open-source-project . Ideally, I would like to include data on session dates etc. from the handbook repository (data/events.yaml): I am thinking about "TODO: codex: create template repository (based on latest...)
TODO: use codex to compare template repo with latest teaching and update before using it as a basis". advise me on how to best approach this.

TODO: also consolidate with https://github.com/fs-ise/quarto-template-presentation

  • Add the new repository to the overview (above)
  • TODO: activate gh page publishing

Publishing to GitHub pages

See tutorial.

For quarto publish gh-pages : install quarto locally (otherwise, the ssh and git setup in the docker container requires detailed configuration).

  • Repository: in the About section, add teaching and teaching-materials as topics.
  • Repository: in the About section, select the GitHub Pages URL.

Repository conformance overview

The repository conformance checks run separately from Quarto rendering. Quarto only includes the previously generated static report fragment below, so rendering the handbook does not clone repositories or call the GitHub API.

Regenerate the report locally with:

make repository-conformance

The scheduled and manually triggered GitHub Actions workflow is defined in update_repository_conformance.yml. For branch-protection checks across repositories, the workflow can use LABOT_PAT_TOKEN when the default GITHUB_TOKEN is not sufficient.

Generated at: 2026-07-20T08:07:32Z.

Statuses: βœ… pass, ⚠️ warning, ❌ fail, βž– not applicable, ❔ not checked, πŸ›‘ error.

Repository Type Overall Pass Warning Fail Not checked Error
fs-ise/analytics-and-big-data materials ❌ Fail 20 1 1 1 0
fs-ise/it-security-management materials πŸ›‘ Error 2 1 2 17 1
fs-ise/mlbd materials ❌ Fail 21 0 1 1 0

Course: ABD β€” Analytics and Big Data

Source page: teaching/courses/2026-SuSe-ABD.qmd

Checked commit: bbb4da66d60b799bd331d4c847d1775f3e5c1a19

Check Status Message
Repository can be accessed βœ… Pass Repository clone is available
Repository is a Quarto project βœ… Pass Found _quarto.yml and QMD files
README is available βœ… Pass Found README.md
License file is available ❌ Fail Missing license file
Default teaching-content license is CC BY ⚠️ Warning Could not detect CC BY license text
Makefile is available βœ… Pass Found Makefile
Bibliography is available βœ… Pass Found references.bib
Quarto config is available βœ… Pass Found _quarto.yml
Index page is available βœ… Pass Found index.qmd
Repository is public βœ… Pass Repository is public
Repository has teaching topic βœ… Pass Found teaching topic
Homepage points to GitHub Pages βœ… Pass Homepage points to GitHub Pages
Default branch is main βœ… Pass Default branch is β€˜main’
Main branch blocks force pushes and deletion ❔ Not checked GitHub API metadata is not available or permission is missing
Syllabus is available βœ… Pass Found syllabus.qmd
Teaching notes are available βœ… Pass Found teaching_notes.qmd
Feedback page is available βœ… Pass Found feedback.qmd
Slides directory is available βœ… Pass Found slides/
Notes directory is available βœ… Pass Found notes/
Exercises directory is available βœ… Pass Found exercises/
Makefile has a pdfs target βœ… Pass Found pdfs target
Session materials use separate files βœ… Pass Found 16 slide source files
Repository has teaching-materials topic βœ… Pass Found teaching-materials topic

Course: ITSecM β€” IT Security Management

Source page: teaching/courses/2026-SuSe-ITSecM.qmd

Checked commit: not available

Repository-level errors: - Cloning into ’/home/runner/work/handbook/handbook/.cache/repository-conformance/fs-ise__it-security-management’… fatal: could not read Username for β€˜https://github.com’: No such device or address

Check Status Message
Repository can be accessed πŸ›‘ Error Repository could not be cloned or opened
Repository is a Quarto project ❔ Not checked Repository is not available
README is available ❔ Not checked Repository is not available
License file is available ❔ Not checked Repository is not available
Default teaching-content license is CC BY ❔ Not checked Repository is not available
Makefile is available ❔ Not checked Repository is not available
Bibliography is available ❔ Not checked Repository is not available
Quarto config is available ❔ Not checked Repository is not available
Index page is available ❔ Not checked Repository is not available
Repository is public ❌ Fail Repository is private
Repository has teaching topic ❌ Fail Missing teaching topic
Homepage points to GitHub Pages ⚠️ Warning Homepage is missing or does not point to GitHub Pages
Default branch is main βœ… Pass Default branch is β€˜main’
Main branch blocks force pushes and deletion ❔ Not checked GitHub API metadata is not available or permission is missing
Syllabus is available ❔ Not checked Repository is not available
Teaching notes are available ❔ Not checked Repository is not available
Feedback page is available ❔ Not checked Repository is not available
Slides directory is available ❔ Not checked Repository is not available
Notes directory is available ❔ Not checked Repository is not available
Exercises directory is available ❔ Not checked Repository is not available
Makefile has a pdfs target ❔ Not checked Makefile is not available
Session materials use separate files ❔ Not checked slides/ is not available
Repository has teaching-materials topic βœ… Pass Found teaching-materials topic

Course: MLBD β€” Machine Learning for Big Data

Source page: teaching/courses/2026-WiSe-MLBD.qmd

Checked commit: 145dbdb292696df21d1333f594cb103a27d60331

Check Status Message
Repository can be accessed βœ… Pass Repository clone is available
Repository is a Quarto project βœ… Pass Found _quarto.yml and QMD files
README is available βœ… Pass Found README.md
License file is available βœ… Pass Found license file
Default teaching-content license is CC BY βœ… Pass Detected CC BY license text
Makefile is available βœ… Pass Found Makefile
Bibliography is available βœ… Pass Found references.bib
Quarto config is available βœ… Pass Found _quarto.yml
Index page is available βœ… Pass Found index.qmd
Repository is public βœ… Pass Repository is public
Repository has teaching topic βœ… Pass Found teaching topic
Homepage points to GitHub Pages βœ… Pass Homepage points to GitHub Pages
Default branch is main βœ… Pass Default branch is β€˜main’
Main branch blocks force pushes and deletion ❔ Not checked GitHub API metadata is not available or permission is missing
Syllabus is available βœ… Pass Found syllabus.qmd
Teaching notes are available βœ… Pass Found teaching_notes.qmd
Feedback page is available ❌ Fail Missing feedback.qmd
Slides directory is available βœ… Pass Found slides/
Notes directory is available βœ… Pass Found notes/
Exercises directory is available βœ… Pass Found exercises/
Makefile has a pdfs target βœ… Pass Found pdfs target
Session materials use separate files βœ… Pass Found 13 slide source files
Repository has teaching-materials topic βœ… Pass Found teaching-materials topic

Resources