liveBook · Manning

Before/after comparison

As explained in "Looks Good to Me"

A presentation that contrasts the state of a software artifact before and after a change.

A before/after comparison contrasts an artifact’s previous and changed states so reviewers can understand intent without reconstructing every detail from code. It is especially useful when a picture can show more than prose. section 2.3.2

Choose a visual aid that matches the change:

  • Use screenshots for layout, styling, responsive behavior, or redesigns. section 2.3.2
  • Use an automatically generated preview deployed to a review environment when reviewers need to inspect the result directly. section 2.3.2
  • Use diagrams or other visual aids for API endpoint hierarchies and file-directory restructures, even when the change is not visual by nature. section 2.3.2

Responsive component change

Instead of listing every styling difference, show the component before and after on tablet, mobile, and TV layouts, then summarize the main differences in the pull request description. section 2.3.2

Table 2.2 Description elements based on categorization prefix
If you used this categorization prefix in the title:
These are some expected components to place in the description:
feat:
Alternatives: 
feat(component or project):
feature:
feature(component or project):
Context/justification
Use cases
How has this been tested?
Preview (if applicable)
Documentation
Tests
fix:
Context/justification
Linked Issue/ticket #
Before-/after-fix comparison
How to test it
Documentation
Tests
docs:
Context/justification
Linked Issue/ticket #
Use cases
Preview (if applicable)
chore:
Context/justification
breaking:
Context/justification
How has this been tested?
Affected projects
Important dates
Mitigation/next steps
Documentation
Tests

For fix-oriented pull requests, include a before-/after-fix comparison alongside context, testing guidance, documentation, and tests. section 2.3.2

How "Looks Good to Me" covers it

How deep it goes
Defines suitable visual aids and use cases but stops short of prescribing a capture or annotation workflow.
Examples
Uses responsive component screenshots, review-environment previews, API endpoint hierarchies, and file-directory restructures.
What it assumes
Assumes familiarity with pull requests and review descriptions while teaching when visual evidence communicates change more effectively than prose.
What you can do after
Apply it via screenshots, generated previews, or diagrams that expose the change and its principal differences.
How it connects
Connects pull request descriptions with code review, screenshots, previews, API hierarchies, and file-directory restructures.
Cover of "Looks Good to Me"
liveBookmanning.com
Read "Looks Good to Me" on liveBook Get the book at manning.com

Related concepts

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.