Reproducibility on Work You Can Explain

Communicating with Instructors During a Technical Crisis

Wed, 19 Aug 2026 00:00:00 -0500

When a technical problem may affect an assignment, contact the instructor as soon as the risk is clear. The message should make the situation easy to understand: identify the course and assignment, describe what happened, state what you have checked, explain the current risk, and make one specific request.

You do not need to prove the final cause before sending the first message. You do need to be accurate about what you observed and what you have tried.

Build a Reproducible Linux Setup

Thu, 30 Jul 2026 00:00:00 -0500

A reproducible Linux setup needs a named target. This walkthrough targets Ubuntu 26.04 LTS, not every Linux distribution. It records the packages, selected user configuration, manual decisions, bootstrap order, and verification needed for one course environment.

The repository will not recreate hardware, firmware, disk layout, encrypted data, online accounts, or every historical application. It should restore required capability on the named target and explain its limits.

Define the exact target

Record:

Build a Reproducible macOS Setup

Thu, 30 Jul 2026 00:00:00 -0500

A reproducible Mac setup is a small, tested description of required capability. It is not a copy of every installed app or a script that overwrites an unknown machine. Record one course environment with a reviewed Brewfile, documented configuration sources, cautious bootstrap steps, and read-only verification.

Begin only after the current environment works and you can explain its parts. If it does not, first complete one course-bounded Mac environment rather than encoding an unverified setup.

Recover a Student Mac from a Broken Setup

Thu, 30 Jul 2026 00:00:00 -0500

Test recovery before a failure, but do not erase, reinstall, or reset a working student Mac for practice. Run a non-destructive rehearsal that verifies account and FileVault responsibility, restores one disposable test artifact, clones one project to a new directory, checks the reproducible setup record, identifies device management, and records the correct macOS Recovery path.

If no setup artifact exists yet, first create the small, secret-free macOS setup record. A recovery rehearsal cannot verify documentation that exists only in memory.

A Project README That Lets Someone Else Succeed

Fri, 24 Jul 2026 00:00:00 -0500

A README succeeds when another person can understand the project and reproduce its expected result without reconstructing your memory. State what the project does, what it requires, how to install, run, test, and verify it, and where to get help.

Write for a defined reader

Name the reader and starting state:

These instructions are for a CS 101 student with Git and Python 3.13 installed who has cloned the repository but has not created the environment.

Build a Reproducible Windows Setup

Fri, 24 Jul 2026 00:00:00 -0500

A reproducible Windows setup is not a screenshot of installed applications. It is a tested set of source artifacts that explains what the student needs, how to establish it, and how to verify the result.

Create a versioned repository containing package IDs, an inspected WinGet export or configuration, small setup steps, secret-free examples, and a verification script. Begin with current course requirements, not every application installed over the computer’s lifetime.

Install Only What the Course Requires

Fri, 24 Jul 2026 00:00:00 -0500

Install the smallest environment that satisfies the course’s documented requirements. Match required versions, keep project dependencies isolated when the ecosystem supports it, retain dependency records, and document how you verified the installation.

More tools do not create a more capable beginner environment. They create more possible sources of version and path conflicts.

Start with course evidence

Before downloading anything, collect:

the syllabus and current assignment instructions;
an instructor-provided setup guide;
the starter project’s README and configuration files;
required language and tool versions;
supported operating systems;
required editor or IDE, if any;
dependency installation commands; and
the exact command used to run or test the first exercise.

Treat a classmate’s setup, an old video, and an AI-generated list as leads, not authority. They may describe another semester or operating system.

Rebuild a Student Windows PC from Documentation

Fri, 24 Jul 2026 00:00:00 -0500

Test recovery before a device failure, but do not reset a working student computer for practice.

Run a non-destructive rehearsal: inventory accounts and recovery access, restore test files to another location, clone a project into a new directory, inspect package manifests, follow setup documentation, and run verification. Record every missing dependency.

An actual Windows reset or reinstall is a separate destructive operation. It requires a real need, complete backup, BitLocker recovery access, official instructions, time, power, network access, and authorization for managed devices.

Write a Reproducible Bug Report

Fri, 24 Jul 2026 00:00:00 -0500

A useful bug report lets another person reproduce the failure or understand why they cannot. Include the environment, exact steps, expected and actual behavior, complete errors, and the smallest safe example that still fails.

Write a specific title

Use observable behavior:

CSV summary rejects a valid header containing spaces

Avoid “program broken” or a diagnosis you have not established.

Record the environment

Include only relevant facts:

operating system and version;
application, runtime, or library versions;
installation method;
current directory or repository commit;
configuration that changes behavior; and
hardware only when plausibly relevant.

Use commands or application information screens rather than memory. Redact usernames, device names, tokens, internal URLs, and private paths.