Module 2: Developer Environment: Case Studies
These cases make environment setup observable and reproducible instead of a collection of one-off fixes.
Case Study 1: The Project Works Only on One Laptop
Scenario: A beginner can run code on their machine, but teammates fail because the README omits runtime versions, install steps, environment variables, and verification commands.
Source anchor: VS Code getting started documentation.
Module concepts:
- reproducible setup
- terminal workflow
- environment variables
- verification scripts
Wrong Approach
Tell teammates to reinstall tools until the project works.
Better Approach
Document prerequisites, exact commands, expected output, and known failure modes. Add a smoke test that proves the environment is ready.
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| Tribal setup | Fast for one person | Fails for others |
| Setup checklist | Reproducible onboarding | Must be maintained |
| Automated setup script | Fewer manual steps | Can hide important assumptions |
Failure Mode
The first project week is spent debugging machine differences instead of learning.
Required Artifact
Write a setup README section with tool versions, install commands, smoke test, and troubleshooting table.
Project / Capstone Connection
Use this exact setup section format in every later project README so teammates and reviewers can reproduce your environment without tribal knowledge.
Case Study 2: Terminal Fear During Debugging
Scenario: A learner uses the editor run button only. When a command fails in CI, they cannot reproduce it locally or inspect paths, exit codes, and logs.
Source anchor: VS Code integrated terminal documentation.
Module concepts:
- shell basics
- working directory
- exit codes
- command logs
Wrong Approach
Click around the IDE until the visible error disappears.
Better Approach
Run the same command in the terminal, record working directory, command, output, exit code, and next hypothesis. Treat terminal use as a debugging instrument.
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| IDE-only workflow | Comfortable | Hard to reproduce CI |
| Terminal-first checks | Transparent execution | Requires command fluency |
| Saved command log | Debuggable history | Slight overhead |
Failure Mode
The learner fixes a symptom in the IDE but cannot explain why CI still fails.
Required Artifact
Create a command journal with five common commands, expected output, failure output, and recovery step.
Project / Capstone Connection
Keep extending this journal during later semesters; it becomes the base for debugging notes, build instructions, and operational runbooks in portfolio projects.
Case Study 3: Secrets in Local Configuration
Scenario: A project stores API keys in a committed config file so setup feels easy. A later repository share exposes the keys.
Source anchor: The module's environment and project hygiene guidance.
Module concepts:
- secrets handling
.envfiles.gitignore- configuration boundaries
Wrong Approach
Commit real credentials and rotate them only if someone notices.
Better Approach
Use example configuration files, local ignored .env files, and startup validation that reports missing variables without printing secrets.
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| Commit secrets | Easy setup | Security incident |
.env.example | Safe onboarding | Requires local configuration |
| Secret manager | Stronger controls | More tooling |
Failure Mode
A public repository accidentally contains live credentials.
Required Artifact
Write a configuration checklist with secret locations, ignored files, required variables, and validation behavior.
Project / Capstone Connection
Apply this checklist to every later service or app so deployment, onboarding, and security review all start from the same configuration discipline.
Case Study 4: Version Drift Breaks The Build
Scenario: A project works on one laptop because it uses Node 22, but a teammate has Node 18 and sees different dependency behavior and test failures.
Source anchor: The Twelve-Factor App: Config is a good anchor for separating environment-specific settings from code; the same discipline applies to runtime version declarations and reproducible local setup.
Module concepts:
- runtime versioning
- reproducible builds
- lockfiles
- setup verification
Wrong Approach
Assume the latest local runtime is close enough.
Better Approach
Declare supported runtime versions, keep dependency lockfiles committed, and make the smoke test fail early when the runtime is outside the supported range.
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| implicit runtime | zero setup work | inconsistent behavior across machines |
| pinned versions | reproducibility | occasional upgrade work |
| version manager instructions | easier onboarding | another tool to learn |
Failure Mode
The team wastes time debugging dependency differences that are really environment mismatches.
Required Artifact
Add a runtime-compatibility section to the setup guide with supported version, check command, lockfile note, and upgrade rule.
Project / Capstone Connection
Use this runtime-compatibility section in every later repo so builds fail fast for version mismatches instead of drifting silently.
Case Study 5: The Command Fails Because The Working Directory Is Wrong
Scenario: A learner runs pytest or npm run build from the wrong folder, sees missing-file errors, and starts reinstalling tools even though the real issue is path context.
Source anchor: VS Code integrated terminal documentation is a practical reminder that terminal commands execute within a concrete workspace and directory context.
Module concepts:
- working directory
- relative paths
- shell context
- reproducible commands
Wrong Approach
Treat every command failure as a tooling or dependency problem.
Better Approach
Check the current directory, confirm which project root the command expects, and document commands relative to that root. Include verification commands like pwd or repository-root checks in setup instructions where beginners are likely to drift.
Tradeoff Table
| Choice | Gain | Cost |
|---|---|---|
| implicit directory assumptions | fewer words in docs | high beginner confusion |
| explicit project-root commands | reproducible execution | slightly longer instructions |
| helper scripts from repo root | simpler onboarding | one more layer to maintain |
Failure Mode
The learner keeps changing the environment when the command would succeed immediately from the correct location.
Required Artifact
Add a run from repository root note and a path-verification command to the setup guide for one project.
Project / Capstone Connection
Carry this command-context discipline into later CI, deployment, and runbook instructions so operational commands are anchored to the right workspace every time.
Source Map
| Source | Use it for |
|---|---|
| VS Code getting started documentation | Grounding terminal usage, workspace context, and local execution habits in an environment beginners actually use. |
| The Twelve-Factor App: Config | Justifying separation of environment-specific configuration from committed code and from runtime-version assumptions. |