From aef61a21062737f18119c5d9f9c8ffc599824f33 Mon Sep 17 00:00:00 2001 From: Joris Wouter Jonkers Date: Thu, 17 Sep 2026 10:48:38 +0200 Subject: [PATCH] chore: move the course hand-outs into a private submodule The lecture decks and the background reading are third-party works, so they are not ours to publish. They move to the private repository JorisJonkers-dev/mde-course-material, mounted at docs/mde/course-material, and main's history no longer carries them. The reports stay public, and assignment.md records what each task requires so the task text is readable without the hand-outs. No relative link points into the submodule: an uninitialised submodule is an empty directory, and every such link would fail the link gate on a fresh clone. --- .gitmodules | 3 + AGENTS.md | 26 ++++-- docs/mde/README.md | 32 +++++--- docs/mde/assignment.md | 147 ++++++++++++++++++++++++++++++++++ docs/mde/course-material | 1 + scripts/lib/change-buckets.ts | 1 + test/change-buckets.test.ts | 1 + 7 files changed, 193 insertions(+), 18 deletions(-) create mode 100644 .gitmodules create mode 100644 docs/mde/assignment.md create mode 160000 docs/mde/course-material diff --git a/.gitmodules b/.gitmodules new file mode 100644 index 0000000..ef64188 --- /dev/null +++ b/.gitmodules @@ -0,0 +1,3 @@ +[submodule "docs/mde/course-material"] + path = docs/mde/course-material + url = https://github.com/JorisJonkers-dev/mde-course-material.git diff --git a/AGENTS.md b/AGENTS.md index 9e80c71..083486f 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -280,10 +280,22 @@ as dead. ## MDE coursework material -`docs/mde/` holds a university course's reports, lecture decks and background -reading. Every PDF there has a Markdown conversion beside it, with its -figures in a sibling `-images/` directory. **Start from -[`docs/mde/INDEX.md`](docs/mde/INDEX.md)**: it says which document covers -which topic, down to the section anchor and the PDF page, so open one section -of one `.md` rather than reading a PDF end to end. Some of these run to 400 -pages. +`docs/mde/` holds a university course's reports: one directory per task, plus +[`docs/mde/assignment.md`](docs/mde/assignment.md), the course's own task text, +which says what each task requires and hands in. +[`docs/mde/README.md`](docs/mde/README.md) says which directory mirrors which +task. + +The course's own hand-outs (the lecture decks, the background reading and the +index over them) are **not in this repository**. They are third-party works, so +they live in the private repository `JorisJonkers-dev/mde-course-material`, +mounted as a submodule at `docs/mde/course-material/`. With access, +`git submodule update --init docs/mde/course-material` fetches them; without it +the directory is empty, and nothing here depends on it. No gate reads the +submodule, and CI does not initialise it. + +Once initialised, **start from `docs/mde/course-material/INDEX.md`**: it says +which document covers which topic, down to the section anchor and the PDF page, +so open one section of one `.md` rather than reading a PDF end to end. Some of +these run to 400 pages. Never copy that material into this repository, and never +quote it at length in a tracked file here. diff --git a/docs/mde/README.md b/docs/mde/README.md index 083541e..3dd0651 100644 --- a/docs/mde/README.md +++ b/docs/mde/README.md @@ -30,17 +30,27 @@ in its row above when its Overleaf project exists. ## Course material -Two further directories hold what the course hands out, kept for reference while -the reports are written and not material of this repository: -[`lectures/`](lectures/) for the slide decks and -[`background/`](background/) for the reading set per lecture. Both carry a README -naming every file, because the names publishers and lecture exports ship with -say nothing at a glance. - -Every PDF has a Markdown conversion beside it — `.md`, figures in -`-images/` — produced with docling. **[`INDEX.md`](INDEX.md) maps topics -to documents, sections and PDF pages**; read it first, then open only the -section it points at. +What the course hands out is **not in this repository**. The slide decks, the +background reading per lecture and the index over them live in the private +repository `JorisJonkers-dev/mde-course-material`, mounted here as a submodule at +`docs/mde/course-material/`. They are third-party works under their publishers' +and the course staff's terms, so they are not ours to publish; the reports in +this directory are the author's own work and stay public. + +With access, fetch them in place: + +```bash +git submodule update --init docs/mde/course-material +``` + +The submodule then holds `lectures/` for the decks, `background/` for the reading +set per lecture, and `INDEX.md`, which maps topics to documents, sections and PDF +pages. Read that index first; several of those documents run to 200-400 pages. +Every PDF has a Markdown conversion beside it, `.md`, with figures in +`-images/`, produced with docling. + +Without access the directory stays empty and nothing else in this repository +depends on it: no gate reads it, and CI does not initialise submodules. ## Layout of a report directory diff --git a/docs/mde/assignment.md b/docs/mde/assignment.md new file mode 100644 index 0000000..37543b2 --- /dev/null +++ b/docs/mde/assignment.md @@ -0,0 +1,147 @@ +# The project assignment + +What the course asks for, task by task, as the Canvas assignment pages state it. +This is the source the report directories are written against: +[`README.md`](README.md) says which directory mirrors which task and when it is +due; this file says what the task itself requires and what has to be handed in. + +The course sets three project types — **Code generation**, **Interoperability** +and **Model discovery ("Harvesting")**. This project is of type **code +generation**, chosen and approved in Task 0, so only that type's task text is +reproduced below. The three types are listed in +lecture 0, `course-material/lectures/lecture-0-introduction.md`, under *Project types*, and the practical +sessions that carry each technology in +the same deck's practical-session schedule. + +## What the type is + +> MDE can be applied to automatically generate code from more abstract models. +> The classic straightforward example is the generation of Java code skeletons +> from UML class diagrams. Another example is to start with RDF +> (), which is a technique to describe related data in a +> network such as the Web, and define transformations that transform RDF models +> into textual graph representations (code) that can be visualised with a tool +> like Graphviz (see ). In this type of project you +> will build a simple tool to generate code from an abstract model. + +## Task 0 — Problem selection + +Due 11 September, 23:59. One PDF per group, file upload, 1 point, **not graded**: +it is an approval gate, and the group may not start the project until the teacher +approves it. + +> In this task you have to select the code generation problem that you will solve +> in your project. The deliverable of this task is a succinct description (max. 2 +> A4 pages) of the problem that you want to solve. The description should mention +> the kind of code that you want to generate from which abstract models. This +> description should be approved by the teacher of the course before you can +> start your project. + +The proposal must also state which of the three project types it is, and detail +the objectives of the project, "also mentioning the languages/metamodels +involved". + +Mirror: [`task-0-proposal/`](task-0-proposal/) — approved. + +## Task 1 — Metamodelling + +Due 25 September. + +> Define a metamodel for your abstract model. Make sure your metamodel can +> properly represent the intended models. +> +> Define a metamodel for the code of your choice. + +Deliverables: + +> Report describing the domain analysis, the modelling decisions you have taken, +> the alternatives you have encountered, the description of the metamodels and +> diagrams of the metamodels, and example models. +> +> Metamodels and models as ECore files. + +So Task 1 hands in **two** metamodels — one for the abstract (source) model and +one for the code (target) — as Ecore, with example models, plus a report covering +domain analysis, decisions, the alternatives considered, and diagrams. + +Mirror: [`task-1-metamodelling/`](task-1-metamodelling/). The Ecore files are +under [`emf/bundles/metamodel/model/`](../../emf/bundles/metamodel/model/). + +## Task 2 — Transformations + +Due 16 October. + +> The purpose of this task is to define a transformation from the abstract models +> to instances of your code metamodel. In this task you define and implement a +> model transformation for this purpose using ATL or QVT OM. + +Deliverables: + +> Report describing the transformation, the modelling choices and the possible +> limitations of the proposed solution. +> +> Evidence that the transformation works. + +Mirror: `task-2-transformations/` — not started. This project uses **QVT +Operational**, not ATL. + +## Task 3 — Code generation + +Due 30 October. + +> In this task, you will implement the model-2-text transformations to generate +> the code from the models in Task 2. You should perform the following +> activities: +> +> - Write a model-2-text transformation in Acceleo. +> - Execute the transformation to generate the code that represents a couple of +> the models from Task 2. +> - Load the generated code in a tool that can handle the code to show that your +> transformation works. + +Deliverables: + +> - Report describing the model-2-text transformation logic, the design +> alternatives and the decisions. +> - The transformation specification, source models and the generated code, with +> evidences that the transformation works. + +Mirror: `task-3-code-generation/` — not started. "Load the generated code in a +tool that can handle the code" is, for this project, applying the generated +manifests to a Kubernetes cluster, or validating them against the API server. + +## Presentation and grading + +Each student presents at least once, for individual grading, and both students +answer questions afterwards. Task 0 carries no mark; Tasks 1, 2 and 3 are +submitted and graded. The grading formula is in +lecture 0, under *Formula for the final grade*, and the LLM policy under +*Use of LLMs*, both in `course-material/lectures/lecture-0-introduction.md`. + +## Project ideas the course offers + +Given as examples of what a code-generation project can look like; none of them +is this project, which generates deployment manifests instead. + +- **Microservices from UML, following Domain-Driven Design.** DDD organises a + complex domain as a network of **Bounded Contexts**, classifies objects into + Entities, Value Objects and Service Objects (the Evans classification), and + identifies **Aggregates**; a Ubiquitous Language embeds the domain's + terminology in the software itself. The Bounded Context is what usually + delimits a microservice. See Fowler, + [Domain-Driven Design](https://martinfowler.com/bliki/DomainDrivenDesign.html). +- **A domain-specific language translated to an executable language**, for + analysis or simulation: for example a language for the flow of goods in a + supply chain, translated to a process model and then to Java or Python. A past + project translated abstract models of user interfaces to a Swing + implementation through an intermediate transformation. +- **Embedded systems.** Code generation is one of the main applications of + model-driven development for embedded systems, where it makes development less + error-prone and less dependent on an experienced embedded developer. See + Böhm, Broy, Klein, Pohl, Rumpe and Schröck (eds.), + [*Model-Based Engineering of Collaborative Embedded Systems: Extensions of the SPES Methodology*](https://link.springer.com/book/10.1007/978-3-030-62136-0), + Springer, 2021. + +The course material this assignment draws on is indexed in +`course-material/INDEX.md`, in the private submodule this repository does not +publish; see [`README.md`](README.md). diff --git a/docs/mde/course-material b/docs/mde/course-material new file mode 160000 index 0000000..72a3399 --- /dev/null +++ b/docs/mde/course-material @@ -0,0 +1 @@ +Subproject commit 72a33992a2c2f8a380a6e07b551b7b940908e85e diff --git a/scripts/lib/change-buckets.ts b/scripts/lib/change-buckets.ts index 1962cc5..e372b56 100644 --- a/scripts/lib/change-buckets.ts +++ b/scripts/lib/change-buckets.ts @@ -53,6 +53,7 @@ const ROOT_TOOLING_FILES = new Set([ ".editorconfig", ".gitignore", ".gitattributes", + ".gitmodules", ".gitleaks.toml", ".npmrc", ".mcp.json", diff --git a/test/change-buckets.test.ts b/test/change-buckets.test.ts index ed5d677..6977ae4 100644 --- a/test/change-buckets.test.ts +++ b/test/change-buckets.test.ts @@ -48,6 +48,7 @@ describe("bucketOf", () => { it("places a root tooling file by its exact name", () => { expect(bucketOf("package.json")).toBe("tooling"); expect(bucketOf(".nvmrc")).toBe("tooling"); + expect(bucketOf(".gitmodules")).toBe("tooling"); }); it("prefers decision records over the wider documentation bucket", () => {