◇ OpenCyber Academy
Engineering · Chapter 14 · English

Chapter 14 — Software engineering

Open, free learning for anyone who wants to protect people and technology. No account is required to read this text or its worked answers.

Chapter 14 — Software engineering

Lesson map

Lesson 14 published. Map, example, EX040.

flowchart TD
  N0["Learning outcomes"]
  N1["14.1 Version control"]
  N2["14.2 Reviews"]
  N3["14.3 Requirements"]
  N4["14.4 Tests"]
  N5["14.5 Releases"]
  N6["Change history in practice"]
  N7["Code review checklist"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7
  N7 --> EX["Worked example"]
  EX --> Q["Exercise EX040"]

Logical drawing

flowchart LR
  N0["Learning outcomes"]
  N1["14.1 Version control"]
  N2["14.2 Reviews"]
  N3["14.3 Requirements"]
  N4["14.4 Tests"]
  N5["14.5 Releases"]
  N6["Change history in practice"]
  N7["Code review checklist"]
  N0 --> N1 --> N2 --> N3 --> N4 --> N5 --> N6 --> N7 --> Q["EX040"]

[Learning outcomes]
    |
    v
[14.1 Version control]
    |
    v
[14.2 Reviews]
    |
    v
[14.3 Requirements]
    |
    v
[14.4 Tests]
    |
    v
[14.5 Releases]
    |
    v
[Change history in practice]
    |
    v
[Code review checklist]
    |
    v
[Worked example] --> [Exercise EX040]

Learning outcomes

You will (1) manage code with version control and reviews; (2) write requirements and tests; (3) plan releases of images.

14.1 Version control

All scripts, image definitions and configuration files live in a version-controlled repository, so every change is recorded with author and reason.

Before the project, image changes were made directly on a master PC and nobody could say afterwards exactly what had changed. Mateo's repository holds the scripts that build the image, so the image can be rebuilt from scratch and every difference between releases can be read. Marta now asks for the commit reference when someone reports that a release changed something.

14.2 Reviews

Changes are reviewed by another person before use, catching mistakes early.

Mateo's own changes are reviewed by Marta or another member of her team, and theirs by him. The reviewer runs the change on a lab PC as well as reading it. In the first month, reviews caught a script that would have deleted printer settings and a policy that applied to staff laptops by mistake. Both would have reached every branch without the second pair of eyes. Reviews take little time.

14.3 Requirements

Requirements are numbered and testable, such as "R3: USB storage devices are blocked on public PCs".

Numbering lets tests, reviews and reports refer to requirements exactly. Each requirement says what must be true, on which PCs and how it is checked. Mateo rewrote several of Fernhill's older rules that said things like keep PCs safe, which nobody could test. Requirements that cannot be tested are either sharpened or moved to a list of goals. Each requirement also names its owner.

14.4 Tests

Each requirement has a test, run on a lab PC before an image is released.

Mateo's tests are mostly short scripts that check a setting or try an action that should fail, such as mounting a synthetic USB storage device. Each test names the requirement it checks and prints pass or fail. Running them takes a few minutes, which means they actually get run before every release instead of being skipped when the team is busy. Failures block the release.

14.5 Releases

New golden images are released in stages: lab PC, one branch, then all branches, so problems affect few PCs first.

Each stage lasts long enough to see normal use, usually a few days at the pilot branch. Marta watches the dashboard and the help requests from that branch before approving the next stage. If a problem appears, the remaining branches stay on the previous image while it is fixed. The release record lists each stage, its dates and who approved moving on.

Change history in practice

When the catalogue app broke last year, nobody could say what had changed. With version control, every image change has a record. If a new image causes problems, the team can compare it with the previous release line by line and roll back quickly. Mateo demonstrates this on a lab PC to convince Marta, who had worried that the repository would be extra work.

The repository also stores the test results for each release.

Code review checklist

Reviews use a short checklist: does the change match a requirement, has it been tested, and does it change anything outside the public PC image?

Testing images

Each image release runs the requirement tests on a lab PC. A release cannot move to branches until all must-have tests pass. This rule is enforced by the release checklist.

Worked example

Marta asks why not update all PCs at once. Mateo explains that staged releases limit the impact of a bad image, citing Fernhill's past experience of an update breaking the catalogue app on every PC.

Synthetic case. Synthetic.

Errors and limits

Without tests tied to requirements, reviews check style rather than function.

Exercises

Synthesis

Engineering discipline applies to images and scripts as much as to applications.

Continue studying — chapter 14 of 50

← Chapter 13 (draft) · Course chapter index · Chapter 15 (draft) →