Lesson 2 of 4 · 60 min

Make the demo reproducible on an ordinary laptop

Produce a demo contract with fixture, command, expected output, and reset behavior.

A demo is a small software product with a learning purpose. It needs a known starting state, declared dependencies, an expected result, and a way to recover when something fails. A presenter who can run it on one prepared laptop has not yet shown that another developer can reproduce it.

Keep the central mechanism local when a paid service is not necessary to teach it. A fixture can demonstrate deduplication, pagination, or error classification without a cloud account. Label the fixture as simulated. Explain which behavior remains unverified, such as provider authentication, real retry timing, or deployment permissions. The boundary makes the example trustworthy rather than less impressive.

Pin or state the runtime and dependency assumptions. A command that works only because the presenter's shell already contains credentials is incomplete documentation. Include placeholder values that are clearly placeholders, expected output, and the most common setup failure. Never put working secrets in a shared sample.

A reset path matters because learners repeat steps. If the first run creates a record and the second run fails unexpectedly, the learner cannot tell whether the concept or their environment is wrong. Choose idempotent setup, an isolated temporary workspace, or an explicit cleanup command that only touches the demo's own data.

Worked example

This fictional local Python example teaches stable event identity. It requires Python 3 and no external package or account.

python

1events = [2	{"id": "E1", "amount": 10},3	{"id": "E1", "amount": 10},4	{"id": "E2", "amount": 5},5]6seen = set()7total = 08for event in events:9	if event["id"] in seen:10		continue11	seen.add(event["id"])12	total += event["amount"]13print(total)

The expected output is 15. The set resets on every run, so the example teaches single-run deduplication only. It does not provide durable protection across restarts or concurrent workers. A later production lesson must move identity and effect into an appropriate durable transaction.

Package the smallest repeatable run

A runnable snippet is not a complete demo contract until another person knows where to put it and what to expect. For the shown Python example, the learner can save the snippet as a file in a dedicated exercise directory and run it with their Python 3 command. The instructions should name the file and state that it uses only the standard library. This manuscript contains the code as teaching material; it does not ship or claim verification of an executable repository.

A run card can be explicit:

code

1Fixture: E1/10, E1/10, E2/52File: event-demo.py in a dedicated learner workspace3Run: python3 event-demo.py4Expected stdout:155Persistent state: none6Reset: rerun; process-local seen and total start empty7Verified scope: deterministic single-run identity handling8Not demonstrated: durable or concurrent deduplication, external delivery

The reset note prevents an apparent contradiction. Repeating the script prints 15 again because each run starts empty. It does not remember that a previous process already handled E1. That behavior is correct for this teaching scope and insufficient for a service that promises one lifetime effect.

Add a conflict-aware variant

The original set records only whether an ID appeared. A stronger teaching variant keeps the payload value for each ID so it can distinguish identical delivery from a conflicting repeated identity. This code still runs locally and still lacks durable concurrency protection.

python

1def total_once(events):2	seen = {}3	total = 04	for event in events:5		event_id = event["id"]6		amount = event["amount"]7		if event_id in seen:8			if seen[event_id] != amount:9				raise ValueError("conflicting payload for " + event_id)10			continue11		seen[event_id] = amount12		total += amount13	return total

For E1/10, E1/10, E2/5, the function returns 15. For E1/10, E1/99, it raises a conflict rather than silently selecting the first value. The exception behavior is part of the teaching contract. If the application needs partial acceptance or a quarantine list, that is another explicit policy, not an automatic property of a dictionary.

The code assumes every event has id and amount, and amounts support the intended addition. It does not validate types, numeric range, or missing fields. State these assumptions instead of claiming complete input validation. A later exercise can add schema checks, but the core example should remain small enough to inspect.

Show the boundary that the variant still lacks

Imagine two processes each run total_once on the same events. Each has its own dictionary and each produces 15. A shared external effect, such as granting a credit, could therefore happen twice. Moving from a set to a dictionary added conflict detection within one run; it did not add coordination across processes.

A durable service needs an authoritative uniqueness or operation contract at the effect boundary. If the effect is an external email, a local transaction alone cannot make the external send atomic with the database. The teaching next step should name the uncertainty and point to the relevant provider's recovery contract. Do not let a successful local total imply a guarantee it cannot establish.

Design a useful failure fixture

Include a small matrix of cases: identical repeated ID, distinct IDs with equal values, conflicting repeated ID, empty list, and missing required field. For each, state expected output or explicit rejection under the chosen version. The original set and conflict-aware variant intentionally differ on the conflict case, so label which version the learner is running.

A fixture should reveal one misconception at a time. If every row is malformed, learners may spend time on syntax rather than identity. Start with the core case, then add a deliberate contrast. Avoid relying on a remote service to create a rare failure during a live teaching session when a local fixture can expose the same concept deterministically.

Misconceptions and a second exercise

One misconception is that pinning a version proves portability. It improves reproducibility, but operating-system commands, paths, and undeclared dependencies can still differ. Another is that a reset should delete a broad directory. A demo reset should affect only its own explicit state; this example needs no deletion at all.

Exercise: add E3/7 and repeat E2/5 in the conflict-aware variant, then add E1/99. The first change returns 22; the conflict case raises rather than returning a total. Explain why keeping 22 as if the full input succeeded would misrepresent the function's contract. Award one point for each result, one for explaining conflict rejection, and one for naming the remaining durability limitation.

A good demo can be small and impressive because the learner can predict, run, inspect, and reset it. Its credibility comes from a precise verified scope, not from calling a ten-line example production-ready.

Exercise and solution

Add E3 with amount 7, then repeat E2. Predict the output before running or tracing the code. The answer is 22 because E3 contributes once and the repeated E2 contributes nothing. Next, change the repeated E1 amount to 99. The original set-based example still prints 22, revealing that it silently ignores conflicting duplicate payloads. The conflict-aware function instead raises an error. Award one point for each prediction and one for proposing explicit conflict detection in a stronger version.

Interview probe and wrap-up

Why show a simple set when production needs a database? A strong answer explains the learning objective, labels the missing durability and concurrency, and connects the next lesson to those limits. Follow up with a learner copying the snippet into production. A weak answer calls it production-ready deduplication. The best demo makes one mechanism visible while stating exactly where the demonstration stops.

Sources

docsGoogle code-sample style guidancedevelopers.google.com docsGitHub open-source contribution guideopensource.guide docsGitLab Developer Advocate rolehandbook.gitlab.com

Checkpoint

Running the process-local demo twice prints 15 twice. What does this establish?

AExternal email exactly once.BLifetime deduplication across runs.CDurable shared state.DSingle-run behavior; each process starts empty.

Checkpoint

The conflict-aware variant sees E1/10 then E1/99. Result?

AReturn 109.BRaise the declared conflicting-payload error.CReturn 99 as latest value.DReturn 10 and claim all input accepted.

Checkpoint

Two processes run the same dictionary code. What is still missing for one shared business effect?

AAuthoritative durable coordination at the effect boundary.BA separate dictionary in each worker initialized with the same fixture.CA larger dictionary limit while state remains process-local.DA log of both successful runs without an authoritative effect constraint.

Checkpoint

The script initializes its dictionary and total on every new process and writes no persistent state. How should the tutorial define a repeatable reset?

ADelete the Python bytecode cache before each run so event identities cannot survive.BKeep one interpreter session and rerun only the event loop against its existing dictionary.CStart a new script process; its initializers restore the stated empty dictionary and zero total.DReplace fixture IDs on each run so the process treats them as unseen events.

Checkpoint

Why include distinct IDs with equal amounts?

ATo prove amounts are unique identifiers.BTo reveal a mistaken value-based deduplication rule.CTo test only installation.DTo show all repeated values should be rejected.

Can you specify a repeatable run, predict conflict-aware behavior, and explain exactly which production guarantees remain outside the demo? State the relevant identifiers, failure boundary, and evidence in your own words before selecting your confidence.

Not yetGetting thereConfident

Sources

Free to read · better with Enzo

Learn it with Enzo

Save your progress, answer the checkpoints, and let Enzo quiz you on what you just read.

Continue with Enzo Sign up free