Week 3: Reading the inscriptions

Commit messages as primary sources — what they reveal about team culture, communication norms, and working conditions.

8 March 2027

Open the slides

Learning outcomes#

By the end of this week you should be able to:

1. classify a corpus of commit messages and infer communication norms from the distribution
2. read version-control trailers as provenance metadata
3. identify what the documentary record structurally cannot contain

Outline#

• The commit message as a genre: conventions (Conventional Commits, Angular, kernel style) and what choosing one says about a team
• The information hierarchy: subject line, body, trailers, co-authors
• What terse messages mean: velocity, solo work, exhaustion, or indifference?
• Case study: the Linux kernel — Torvalds’s merge-commit messages as editorial commentary on other people’s code
• The Signed-off-by trailer and the Developer Certificate of Origin: provenance tracking as archaeological metadata
• What commit messages cannot tell you: the conversation that happened before the code was written

Required reading#

• Tornhill, A. (2018) Software Design X-Rays: Fix Technical Debt with Behavioral Code Analysis. Pragmatic Bookshelf. Chapters 1–4.
• Bodel, J. (ed.) (2001) Epigraphic Evidence: Ancient History from Inscriptions. Routledge. Introduction.

Further reading#

• Conway, M.E. (1968) ‘How Do Committees Invent?’, Datamation 14(5), pp. 28–31.
• Dias, M., Bacchelli, A., Gousios, G., Cassou, D. and Ducasse, S. (2015) ‘Untangling Fine-Grained Code Changes’, SANER 2015.

Seminar questions#

1. Bodel warns that surviving inscriptions over-represent those with the resources to commission them. What is the equivalent survivorship bias in a commit log?
2. A team adopts Conventional Commits in month fourteen. What does the adoption date tell you that the convention itself does not?
3. Can a commit message be evidence of morale, or only of convention? What would distinguish the two?