From 4f2655e86490a77159d18a351ee072a18b468c09 Mon Sep 17 00:00:00 2001 From: Aleksandra Nenadic Date: Tue, 27 Jan 2026 13:21:09 +0000 Subject: [PATCH] Replace svg diagrams with mermaid where possible. Fixes #507. --- episodes/00-setting-the-scene.md | 26 +++++++--------- episodes/10-section1-intro.md | 35 ++++++++++------------ episodes/14-collaboration-using-git.md | 31 ++++++++----------- episodes/20-section2-intro.md | 34 +++++++++------------ episodes/30-section3-intro.md | 37 +++++++++++------------ episodes/40-section4-intro.md | 40 ++++++++----------------- episodes/41-code-review.md | 10 ++----- episodes/50-section5-intro.md | 41 ++++++++++---------------- 8 files changed, 99 insertions(+), 155 deletions(-) diff --git a/episodes/00-setting-the-scene.md b/episodes/00-setting-the-scene.md index f25e28120..89500f330 100644 --- a/episodes/00-setting-the-scene.md +++ b/episodes/00-setting-the-scene.md @@ -56,24 +56,18 @@ and sustain in the future by yourself and others. Skills and tools taught here, while Python-specific, are transferable to other similar tools and programming languages. -The course is organised into the following sections: - -![Course overview diagram](fig/course-overview.svg){alt="Course overview diagram. Arrows connect the following boxed text in order: 1) Setting up software environment 2) Verifying software correctness 3) Software development as a process 4) Collaborative development for reuse 5) Managing software over its lifetime."} - - ```mermaid -flowchart LR - A(1. Setting up software environment) -> B(2. Verifying software correctness) - B -> C(3. Software development as a process) - C -> D(4. Collaborative development for reuse) - D -> E(5. Managing software over its lifetime) + flowchart LR + accDescr {Overview of sections in the lesson: setting up development environment, verifying software correctness, the process of software development & engineering, collaborative software development, managing & maintaining software} + A(1. Setting up software environment) --> B(2. Verifying software correctness) + B --> C(3. Software development as a process) + C --> D(4. Collaborative development for reuse) + D --> E(5. Managing software over its lifetime) ``` ---> ### [Section 1: Setting up Software Environment](10-section1-intro.md) diff --git a/episodes/10-section1-intro.md b/episodes/10-section1-intro.md index 33f0500f4..2b3e7224b 100644 --- a/episodes/10-section1-intro.md +++ b/episodes/10-section1-intro.md @@ -31,27 +31,22 @@ As you get more comfortable with different tools and their alternatives, you will select the one that is right for you based on your personal preferences or based on what your collaborators are using. -![Section 1 Overview](fig/section1-overview.svg){alt='Tools needed to collaborate on code development effectively'} - - +```mermaid + flowchart LR + accDescr {Topics on effective collaborating on code development covered in the current section: virtual development environments, version control & sharing code, writing readable code & code standards} + A(1. Setting up software environment + - Isolating & running code: command line, virtual environment & IDE + - Version control and sharing code: Git & GitHub + - Well-written & readable code: PEP8) + A --> B(2. Verifying software correctness) + B --> C(3. Software development as a process) + C --> D(4. Collaborative development for reuse) + D --> E(5. Managing software over its lifetime) +``` Here is an overview of the tools we will be using. diff --git a/episodes/14-collaboration-using-git.md b/episodes/14-collaboration-using-git.md index 9d3605a87..786c932d3 100644 --- a/episodes/14-collaboration-using-git.md +++ b/episodes/14-collaboration-using-git.md @@ -106,27 +106,20 @@ with different parts of the Git infrastructure, including: is to always do a `git pull` before a `git push`, to ensure you have any latest changes before you push your own. - - -![Software development lifecycle with Git](fig/git-lifecycle.svg){ - alt='Development lifecycle with Git. Four parts of Git infrastructure are represented: working tree, staging area, local repository and remote repository, and alongside this various git commands. git add is shown moving files from working tree to staging area. git commit is shown moving files from staging area to local repository. git push is shown moving files from local repository to remote repository and git fetch from remote repository to local repository. git checkout and git merge are both shown as moving files from local repository to working tree. git pull, a shortcut for git fetch followed by git checkout / merge, is shown moving files from remote repository to working tree.' - .image-with-shadow width="600px" -} +```mermaid +sequenceDiagram + accDescr {Basic development lifecycle with Git and commands for moving files between the Git infrastructure: working tree, staging area, local repository, and remote repository.} + Working Tree-->>+Staging Area: git add + Staging Area-->>+Local Repository: git commit + Local Repository-->>+Remote Repository: git push + Remote Repository-->>+Local Repository: git fetch + Local Repository-->>+Working Tree:git checkout + Local Repository-->>+Working Tree:git merge + Remote Repository-->>+Working Tree: git pull (shortcut for git fetch followed by git checkout/merge) +``` ## Checking-in Changes to Our Project diff --git a/episodes/20-section2-intro.md b/episodes/20-section2-intro.md index 20873b959..59a844bf5 100644 --- a/episodes/20-section2-intro.md +++ b/episodes/20-section2-intro.md @@ -33,27 +33,21 @@ so we should try and employ such practices early on. We will also make use of techniques and infrastructure that allow us to do this in a scalable, automated and more performant way as our codebase grows. -![Section 2 Overview](fig/section2-overview.svg){alt='Tools for scaled software testing'} - - +```mermaid + flowchart LR + accDescr {Topics on verifying software correctness covered in the current section: testing frameworks, automating and scaling up testing, and code debugging} + A(1. Setting up software environment) + A --> B(2. Verifying software correctness: + - Testing frameworks + - Automating & scaling testing: CI and GitHub Actions + - Debugging code) + B --> C(3. Software development as a process) + C --> D(4. Collaborative development for reuse) + D --> E(5. Managing software over its lifetime) +``` In this section we will: diff --git a/episodes/30-section3-intro.md b/episodes/30-section3-intro.md index 8ddba6251..6ee0c3cb7 100644 --- a/episodes/30-section3-intro.md +++ b/episodes/30-section3-intro.md @@ -21,30 +21,27 @@ exercises: 0 In this section, we will take a step back from coding development practices and tools and look at the bigger picture of software as a *process* of development. + + +```mermaid + flowchart LR + accDescr {Topics on software engineering process covered in the current section: gathering requirements, software architecture & design, programming paradigms} + A(1. Setting up software environment) + A --> B(2. Verifying software correctness) + B --> C(3. Software development as a process + - Software requirements + - Software architecture & design + - Programming paradigms) + C --> D(4. Collaborative development for reuse) + D --> E(5. Managing software over its lifetime) +``` + > *"If you fail to plan, you are planning to fail."* > > --- Benjamin Franklin -![](fig/section3-overview.svg){alt='Software design and architecture overview flowchart'} - - - ## Writing Code vs Engineering Software Traditionally in academia, software - and the process of writing it - diff --git a/episodes/40-section4-intro.md b/episodes/40-section4-intro.md index c7b97a249..b5fd03954 100644 --- a/episodes/40-section4-intro.md +++ b/episodes/40-section4-intro.md @@ -46,33 +46,19 @@ using **Poetry** to manage our Python dependencies and produce a code package we can use with a Python package indexing service to illustrate these principles. -![](fig/section4-overview.svg){alt='Software design and architecture' .image-with-shadow width="1000px" } - - B(2. Verifying -software correctness) --> C(3. Software development -as a process) --> D(4. Collaborative -development for reuse - - - Code review - - Software documentation - - Software packaging & release - ) --> E(5. Managing software -over its lifetime) - ---> +```mermaid + flowchart LR + accDescr {Topics on collaborative software development covered in the current section: code review, writing software documentation, packaging & releasing software} + A(1. Setting up software environment) + A --> B(2. Verifying software correctness) + B --> C(3. Software development as a process) + C --> D(4. Collaborative development for reuse + - Code review + - Software documentation + - Software packaging & release + ) + D --> E(5. Managing software over its lifetime) +``` diff --git a/episodes/41-code-review.md b/episodes/41-code-review.md index 755e403f0..f7175f585 100644 --- a/episodes/41-code-review.md +++ b/episodes/41-code-review.md @@ -195,11 +195,12 @@ have not seen before. Here is an outline of the process of a tool assisted code review. ```mermaid -%% Must disable useMaxWidth to have the diagram centre -%%{init: { 'sequence': {'useMaxWidth':false} } }%% sequenceDiagram + accDescr {Code review process: a developer submits code, reviewer provides feedback and requests changes, revisions are made, and the code is approved and merged} participant A as Author participant R as Reviewer A->>A: Write some code @@ -214,11 +215,6 @@ sequenceDiagram A->>A: Merge pull request ``` -Generated with Mermaid tool, diagram available at: ---> - -![](fig/code-review-sequence-diagram.svg){alt='Code review process sequence' .image-with-shadow width="600px"} - Recall [solution requirement SR1.1.1](31-software-requirements.md) from an earlier episode. A fictional colleague has implemented it according to the specification diff --git a/episodes/50-section5-intro.md b/episodes/50-section5-intro.md index 7c5a01417..6af9f03b2 100644 --- a/episodes/50-section5-intro.md +++ b/episodes/50-section5-intro.md @@ -30,33 +30,22 @@ how the outside world interacts with and makes use of our software, how others can interact with ourselves to report issues, and the ways we can successfully manage software improvement in response to feedback. -![](fig/section5-overview.svg){alt='Managing software' .image-with-shadow width="1000px" } - - B(2. Verifying -software correctness) --> C(3. Software development -as a process) --> D(4. Collaborative -development for reuse) --> E(5. Managing software -over its lifetime - - - Issue reporting & prioritisation - - Agile development in sprints - - software project management -) - + +```mermaid + flowchart LR + accDescr {Topics on collaborative software development covered in the current section: issue management, project management, agile development} + A(1. Setting up software environment) + A --> B(2. Verifying software correctness) + B --> C(3. Software development as a process) + C --> D(4. Collaborative development for reuse) + D --> E(5. Managing software over its lifetime + + - Issue reporting & prioritisation + - Agile development in sprints + - Software project management) +``` In this section we will: