liveBook · Manning

Capture-and-chronicle approach

As explained in "Looks Good to Me"

A code-review pattern that records the decisions and context produced during collaborative development for later reference.

Use mobbing to perform much of the review in real time, then keep the pull request as a historical record of why the changes were made. Capture decisions, context, and key observations while the team works; a lighter review can then chronicle them. section 12.2.1

A lightweight chronicle records:

  • Why the change was needed and what context shaped it. section 12.2.1
  • Which decisions produced the chosen solution and how the team reached agreement. section 12.2.1
  • Which alternatives were rejected, including solutions that initially seemed right but proved unsuitable. section 12.2.1
Table 12.1 Lightweight chronicle PR checklist
Checklist Item
Information to chronicle
Examples
Why/context
• Why are we making this change? What’s the context behind this change?
• What decisions led to this solution?
• How did we come to an agreement on this solution?
“This change addresses a really esoteric edge case we didn’t catch but recently caused a major production issue (#323).”
“We have to use this (rather than the FetchUser function available in version 9.3) because our internal packaging system is pinned to version 8.9.6. Until this has been updated company-wide, we have to continue using this workaround method.”
Skipped solutions
• What alternative solutions were discussed, and why were they skipped?
• What “gut-feeling” solutions turned out to be wrong?
“We considered Next.js, but they don’t seem to support relative paths for the exported content. They still have an open ticket on GitHub requesting this support, but they are ignoring it.”
“Lambda Functions incur an additional charge when writing to S3, so we skipped.”
Considerations (brought up during mobbing)
• Will these changes impact other teams?
• Other parts of the code base?
• Does this need to be deployed in a certain way?
“This needs to be feature-flagged until the corresponding ‘Seller’ component is ready.”
“With this refactor, we can remove the AccountUtilities library entirely. Let’s place that work in a separate PR, though!”

Use the lightweight chronicle PR checklist to turn mob-session notes into consistent historical context, including reasons, decisions, and skipped alternatives. section 12.2.1

How "Looks Good to Me" covers it

How deep it goes
Explains the capture workflow and checklist contents, while stopping short of detailed review mechanics.
Examples
Uses a production edge case, a version-pinned workaround, and a rejected Next.js option to illustrate useful chronology.
What it assumes
Assumes participation in mobbing or collaborative review and familiarity with pull requests.
What you can do after
Apply it by recording decisions and context during mobbing and transferring them into a lightweight pull-request chronicle.
How it connects
Links mob programming with code review, pull requests, knowledge sharing, and collaborative decision-making.
Cover of "Looks Good to Me"
liveBookmanning.com
Read "Looks Good to Me" on liveBook Get the book at manning.com

This explainer was generated by Manning's knowledge graph from the text of "Looks Good to Me". The section links point to the parts of the book it draws on.