7  The three-organization model

The course is spread across three GitHub organizations, not one. Each has a distinct job, and keeping them separate is what makes the material reusable and citable over time. Two of them, gitforsci and gitforsci-dev, already exist and stay put. The third is the one you create each time you teach: an iteration org.

flowchart TD
    classDef layer fill:#f7f9fc,stroke:#c7d2e0,color:#1f2933;

    C["<b>gitforsci (central)</b><br/>handbook · canonical CITATION.cff · course DOI"]:::layer
    DEV["<b>gitforsci-dev (development)</b><br/>website template · setup · admin (ghclass scripts) · exercise and assignment templates"]:::layer
    IT["<b>gitforsci-00x (iteration)</b><br/>website generated from the dev template · per-cohort material repos"]:::layer

    DEV -->|"generate fresh each cohort"| IT
    C -.->|"canonical citation copied down"| DEV
    C -.->|"canonical citation copied down"| IT

7.1 What each organization is for

7.1.1 The central org: gitforsci

The long-lived, public face of the course. There is one central org, ever. It holds:

  • The website repository, which is this handbook. Note that it is not the course landing page that learners use; that page is generated from a template in gitforsci-dev (see below). The central website is the instructor-facing guide and the overview of how the whole course fits together.
  • The canonical CITATION.cff and the course-level DOI. This is the single source of truth for how the course is cited (Chapter 13).

The central org rarely changes. You only revisit it when the citation changes or when the handbook itself is revised. You do not copy or fork it to run a course.

7.1.2 The development org: gitforsci-dev

Where the teaching material is authored and maintained between cohorts. It holds the templates that each new cohort is generated from:

  • A website template repository: the course landing page learners actually use, the starting point for each cohort’s site.
  • Material repositories: the setup instructions, the admin repository with the ghclass R scripts used to invite learners and create their repositories, and the exercise and assignment templates.

When you improve the material, you do it here. Those improvements reach future cohorts because each new cohort is generated fresh from these templates. Past cohorts stay frozen.

A new instructor does not need to recreate gitforsci-dev. They are added to it as a contributor and propose improvements through pull requests, so the material can get better over time without diverging per cohort. This is what the org’s CONTRIBUTING.md is for: it states how to propose a change, what stays stable between iterations, and how the maintainer reviews and merges. The expectation is small, reviewed improvements, not a rewrite per cohort.

7.1.3 The iteration org: gitforsci-00x

One organization per time the course is taught, and the only one you create to run a course. Name it with an iteration tag, either a number (gitforsci-001, gitforsci-002) or something descriptive (gitforsci-cis, gitforsci-ghe). It holds:

  • A website generated from the gitforsci-dev template: an independent copy with its own clean history and no live link back to the template. This is the site this cohort uses.
  • Per-cohort copies of the material repositories your learners work in.

Each iteration org is a frozen snapshot: the course exactly as you taught it that time. Learners are members of the iteration org, not of the central or development orgs.

7.2 How material and citation flow

Two flows matter, and they go in different directions.

Templates flow forward. When you generate a new cohort from gitforsci-dev, it picks up every improvement made to the templates since the last cohort. Past cohorts do not change; only future cohorts inherit edits. If you ever need to carry a fix into a cohort that already exists, you apply it there as an ordinary commit.

Citation flows down. The canonical CITATION.cff lives in gitforsci/website. When it changes (a new author, a corrected ORCID, a new DOI), you copy it down into the other repositories so everything cites the course the same way. Chapter 13 covers this in full, including how each iteration also gets its own DOI on top of the canonical one.

7.3 Documenting each iteration

The central handbook tells you how to run the course, but the course also learns from every cohort. Each iteration org is a record of how it actually went: which drawings worked, where learners got stuck, what you changed on the day. This handbook keeps a place for that: Chapter 12 is the run-book for the next cohort, and the iteration orgs themselves (starting with https://github.com/gitforsci-cis) are the archive of each run. Capture the specifics there, in issues and in the cohort’s own repositories, so the next instructor benefits from what this one learned.

7.4 Why not just one organization

Splitting the central org from the development org keeps the public identity (the citation, the DOI, the handbook) stable while the messy work of editing material happens elsewhere.

Splitting the development org from each iteration org lets template improvements flow forward to future cohorts without back-contaminating the template with one cohort’s specific dates, names, and URLs. Each past cohort stays exactly as it was taught, which is what makes it a trustworthy archival record, and what lets it carry its own DOI.

New educator — to teach the course once, the only organization you create is the iteration org, generated from the existing gitforsci-dev templates. Chapter 8 walks through it.