Polished Pull Requests

Polished Pull Requests

Francisco, Martijn & TimS

October 2024

1 / 17
volgende
Slide 1: Slide
newEditorSoftwareontwikkelingBeroepsopleiding

In deze les zitten 17 slides, met tekstslides.

Dit is niet oké

Onderdelen in deze les

Polished Pull Requests

Francisco, Martijn & TimS

October 2024

Smooth code reviews

Do you want your PR to be reviewed quickly?


Do you want to stop putting the ticket number in every commit message?




Do you want to quickly understand what is being changed in the PR you are reviewing?

Author

Reviewer

Going back in time

Do you want to easily find the source of changes?


Do you want to understand what changed when and why?


Do you want to not be distracted by noise in the change history?

Historian

A two-pronged approach

Squash merges

Writing informative PRs

Available in GitHub

Use the Merge dropdown menu to select

Mechanics of regular merges (a.k.a. "explicit")

Time

Example: Merge pull request #6956 from lessonup/ED-1136/error-pages-editor

Mechanics of squash merges

Commit message = PR title + description

Time

Commits as snapshots

These commits are useful during development, but lose their function after work is merged.


Squash merges let us treat commits as true snapshots: no one will judge your commit messages. 🎉


We are removing the 1.0 constraint on commit messages. 🎉


What a squashed history looks like

When to use squash merges

Starting today:

  • Squash merges will be the default in GitHub (but you can override this)

  • Commit message checks are removed


✅ Normal development work
(recommended, but not required)


❌ Release branches

❌ Long-lived feature branches

⚠️ Stacking PRs (suggestion: git config --global merge.conflictstyle diff3)


Feel free to message #git-support if you need help

Questions?

Writing informative PRs

Provide context

clear title, helpful description


One self-contained change

easier to design well, easier to review, less likely to introduce bugs, easier to merge, easier to roll back


💡 Especially important with squash commits


Please read https://lessonup.atlassian.net/wiki/spaces/LD/pages/773455900/Code+Reviews

Providing context

Imagine your PR is read some time in the future,

by a colleague from a different team.


Title: short summary

Often the only thing visible in overviews.

Should stand alone and allow readers to skim through code history.

💡 The reader is unlikely to be aware of the context of your work.


Description: more details about what has changed

Add if relevant: how it was changed, why it was changed, related PRs/tickets/docs, screenshots, what to do to test the changes.

⚠️ Linking to a ticket alone is not enough.


Both of these might need updating after code review has completed


More details: https://lessonup.atlassian.net/wiki/spaces/LD/pages/773455900/Code+Reviews

GitHub flow right before merging

GitHub lets you update and confirm your squashed message before merging.

One self-contained change

Rename something and update all its uses

Refactor the Organizations module and add a new API method

Add Microsoft Ad tracking to analytics package and multiple frontend apps

Add existing analytics

to one frontend app

💡 Design the scopes of your PRs before writing them

Your responsibility as reviewer

  • Your job is to help the author write a good PR.

  • Feel free to take the time to review properly.

  • Try to review soon(tm), and help unblock the author.

  • Consider approving even if you ask for changes.

  • Push back if the PR is trying to do too much.

Reviewer

New workflow

We will experiment with the following setup and evaluate after a while.


Automated

  • Simplified PR template

  • Squash merges as default

  • No more mandatory JIRA tickets in commit messages

  • New Github Action to validate JIRA tickets in PR titles (already live)


Your workflow

  • Read the Confluence docs

  • Be vigilant as author and reviewer

  • Consider using squash merges when appropriate

  • Ask questions in #tech-only or #git-support