Git, review & change history
Turn your changes into a sequence that another engineer can understand and safely review.
BY THE END, YOU CAN
- Distinguish working tree, staging area, and commit
- Create a coherent change with a useful explanation
- Review for behavior and risk rather than style alone
Diagram description: main → 1 (branch); 1 → 2; 2 → Review (pull request); Review → merged (approved); main → merged (main moves on)
A commit is a selected snapshot
Git tracks snapshots connected by history.
Your working tree contains current files; the staging area selects what the next commit will contain. A commit records that selected state with metadata and a parent relationship. Before committing, inspect both the full working diff and the staged diff.
Untracked files are not automatically included. Keep generated artifacts and secrets out of history when they do not belong there. A branch is a movable reference to a commit, not a completely separate copy of every file.
Make the change tell one story
A useful change answers three questions: what problem occurred, what behavior changes, and how was it checked?
A small coherent commit is easier to review and revert than a mixture of unrelated cleanup and feature work. Reviewers need the assumptions and edge cases that are not obvious from the code. For Relay, explain why a retry limit changes, how existing jobs are affected, and which tests cover the boundary.
Mention material limitations directly rather than presenting test success as unlimited confidence.
Use disagreement as information
Code review checks correctness, maintainability, compatibility, and operational consequences.
Ask whether inputs can violate an assumption, whether a failure is visible, and whether state changes can leave inconsistent data. Distinguish required fixes from preferences so the author knows what blocks progress. A merge conflict is a textual overlap; resolving it does not prove the combined behavior is correct.
Read the surrounding intent and run relevant checks after resolving. When collaboration is difficult, a tiny runnable example often resolves ambiguity faster than an abstract debate.
COMMON FAILURE MODE
A conflict-free merge can still combine incompatible assumptions. Git understands text and history, not your program's intended semantics.
TRY IT YOURSELF
Write a review description for changing Relay's retry limit. Include the problem, intended behavior, compatibility implications, and one boundary test.
Make the call in the laboratory.
The two-question checkpoint, your notes, and your saved progress are in the laboratory. Free, with no account.
Open in the laboratory ↗CONNECT IT TO RELAY
Create a reviewable Relay change with one clear purpose, a concise rationale, and a recorded verification command.