matt-dray · November 6, 2025 14:41
diff --git a/20251106_coffee_github-pr.txt b/20251106_coffee_github-pr.txt
 # The Strategy Unit C&C, 2025-11-06: collaborating using Github

 ## Focus

 This is about using the GitHub interface for [pull requests (PRs)](https://docs.github.com/en/pull-requests) from the perspective of the assignee (submitter) and reviewer.
 I'm concentrating on a pull request to a repository that you have access to, e.g. in [The-Strategy-Unit GitHub organisation](https://github.com/The-Strategy-Unit/).

 ## Why?

 Pull requests are important because they help:

 * avoid simple mistakes
 * prevent errors
 * improve our code
 * limit 'it works on my machine' syndrome
 * promote coollaboration

 It's a stop-and-breathe opportunity during the coding process.

 PRs are for humans as much as they're for code.
 A chance to discuss things, develop skills and consider different perspectives.

 ## Caution

 Every PR is different.
 Sometimes it's a single typo, sometimes it's adding a feature.
 The more important or riskier the solution is, the more explanation and scrutiny it should probably get.

 Do as I say, not as I do!

 ## Process

 Assuming you have access to the repository and you've pushed your commits to your branch, the [pull-request process](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) in the GitHub interface is like:

 1. Go to your project's repository.
 1. Select your branch from the dropdown, click 'contribute', then 'open pull request' (tip: you can also just 'compare' to see a comparison of your changes against existing branches).
 1. Add yourself as the assignee, choose a reviewer (tip: people can be automatically assigned via [a `CODEOWNERS` file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)).
 1. Give an active title to the PR that says what it will do, e.g. 'Add hospital picker to the user interface'.
 1. In the description, explain more specifically, but succinctly, what you actually did, e.g. 'Added hospital-lookup json file' (tip: I like to do this as a series of easy-to-read bullets, sometimes with images attached).
 1. Link to the issue to give further background to the problem being solved, best done by typing e.g. 'close #1', which will automatically close that issue when the PR is merged.
 1. Click the 'Create pull request' button (tip: click the arrow in the button to optionally open a draft PR, if the work is not yet complete).

 As the reviewer, you'll then:

 1. Be alerted automatically to start the review.
 1. Look through the conversation, commit messages and files tabs in the interface to assess the changes.
 1. Click the '+' next to lines (click and drag for mutiline) in the code interface to leave eave individual comments and suggestions and choose to approve, request changes (with suggestions) or leave comments without a final decision (tip: click the '±' to [directly suggest changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request#applying-suggested-changes) that the user can choose to add to their code with you as a joint commit author).
 1. Choose from 'Comment', 'Approve' and 'Request changes' and click the 'Submit review' button.
 1. Re-review if the user makes the changes and re-requests your review from the PR interface.

 Once approved, it's the assignee's responsibility to merge (this allows the assignee to catch anything fix small things before actually merging).
 So:

 1. Click the 'Merge' button.
 1. Delete your branch (tip: to have branches close automatically, go to 'Settings' in the repo and check 'Automatically delete head branches').
 1. Optionally, tidy up your local branches with `git prune origin main`

 ## Your roles

 As the assignee (submitter), I should:

 * raise PRs and not commit directly to main
 * keep my PR small in code/commits and solve one issue
 * explain: what issue will be closed, what have I changed, any special instructions?
 * tell a 'story' with the PR's conversation, commit messages and files tabs

 As the reviewer, I should:

 * read the story, ask for more information if needed
 * explain what I checked, what I found and give advice
 * reconsider nitpicking, offer broad solutions (i.e. don't force a minor personal preference)
 * be nice: consider the context of the assignee and the 'importance' of the PR

 ## Examples

 A few PR examples:

 * [a recent simple example](https://github.com/The-Strategy-Unit/nhp_analysis/pull/186) that explains what's changed, what needs checking and what it will close.
 * [one of many excellent PRs by Craig](https://github.com/The-Strategy-Unit/nhp_mitigator_comparisons_app/pull/98) that makes good use of sections, explanation and images, while also injecting some levity.
 * [a Copilot PR](https://github.com/The-Strategy-Unit/nhp_inputs/pull/591) that was created to test an LLM for adding boilerplate, which is well presented but perhaps overwhelming.

 ## Going further

 We haven't talked about a lot of things, like:

 * submitting a PR [in someone else's repo](A slightly different approach ([using a 'fork'](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) using a fork
 * fixing [merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github) when your code changes clash with someone else's changes
 * adjusting commit history with [squash and rebase merges](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github)
 * using [GitHub Actions](https://docs.github.com/en/actions) to do things like run tests and checks on pull requests
 * not using the web interface, but using your IDE (e.g. [in VS Code](https://code.visualstudio.com/docs/sourcecontrol/github)) or [the GitHub command line interface](https://cli.github.com/)

 ## Further reading

 There are lots of online resources, here's a few:

 * [Jack's code-review blog](https://jcken95.github.io/projects/code_review.html)
 * [The Tidyverse team's guide](https://code-review.tidyverse.org/)
 * [The SU Data Science website](https://the-strategy-unit.github.io/data_science/style/git_and_github.html#creating-and-reviewing-prs) (you can contribute!)
	# The Strategy Unit C&C, 2025-11-06: collaborating using Github

	## Focus

	This is about using the GitHub interface for [pull requests (PRs)](https://docs.github.com/en/pull-requests) from the perspective of the assignee (submitter) and reviewer.
	I'm concentrating on a pull request to a repository that you have access to, e.g. in [The-Strategy-Unit GitHub organisation](https://github.com/The-Strategy-Unit/).

	## Why?

	Pull requests are important because they help:

	* avoid simple mistakes
	* prevent errors
	* improve our code
	* limit 'it works on my machine' syndrome
	* promote coollaboration

	It's a stop-and-breathe opportunity during the coding process.

	PRs are for humans as much as they're for code.
	A chance to discuss things, develop skills and consider different perspectives.

	## Caution

	Every PR is different.
	Sometimes it's a single typo, sometimes it's adding a feature.
	The more important or riskier the solution is, the more explanation and scrutiny it should probably get.

	Do as I say, not as I do!

	## Process

	Assuming you have access to the repository and you've pushed your commits to your branch, the [pull-request process](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request) in the GitHub interface is like:

	1. Go to your project's repository.
	1. Select your branch from the dropdown, click 'contribute', then 'open pull request' (tip: you can also just 'compare' to see a comparison of your changes against existing branches).
	1. Add yourself as the assignee, choose a reviewer (tip: people can be automatically assigned via [a `CODEOWNERS` file](https://docs.github.com/en/repositories/managing-your-repositorys-settings-and-features/customizing-your-repository/about-code-owners)).
	1. Give an active title to the PR that says what it will do, e.g. 'Add hospital picker to the user interface'.
	1. In the description, explain more specifically, but succinctly, what you actually did, e.g. 'Added hospital-lookup json file' (tip: I like to do this as a series of easy-to-read bullets, sometimes with images attached).
	1. Link to the issue to give further background to the problem being solved, best done by typing e.g. 'close #1', which will automatically close that issue when the PR is merged.
	1. Click the 'Create pull request' button (tip: click the arrow in the button to optionally open a draft PR, if the work is not yet complete).

	As the reviewer, you'll then:

	1. Be alerted automatically to start the review.
	1. Look through the conversation, commit messages and files tabs in the interface to assess the changes.
	1. Click the '+' next to lines (click and drag for mutiline) in the code interface to leave eave individual comments and suggestions and choose to approve, request changes (with suggestions) or leave comments without a final decision (tip: click the '±' to [directly suggest changes](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/reviewing-changes-in-pull-requests/incorporating-feedback-in-your-pull-request#applying-suggested-changes) that the user can choose to add to their code with you as a joint commit author).
	1. Choose from 'Comment', 'Approve' and 'Request changes' and click the 'Submit review' button.
	1. Re-review if the user makes the changes and re-requests your review from the PR interface.

	Once approved, it's the assignee's responsibility to merge (this allows the assignee to catch anything fix small things before actually merging).
	So:

	1. Click the 'Merge' button.
	1. Delete your branch (tip: to have branches close automatically, go to 'Settings' in the repo and check 'Automatically delete head branches').
	1. Optionally, tidy up your local branches with `git prune origin main`

	## Your roles

	As the assignee (submitter), I should:

	* raise PRs and not commit directly to main
	* keep my PR small in code/commits and solve one issue
	* explain: what issue will be closed, what have I changed, any special instructions?
	* tell a 'story' with the PR's conversation, commit messages and files tabs

	As the reviewer, I should:

	* read the story, ask for more information if needed
	* explain what I checked, what I found and give advice
	* reconsider nitpicking, offer broad solutions (i.e. don't force a minor personal preference)
	* be nice: consider the context of the assignee and the 'importance' of the PR

	## Examples

	A few PR examples:

	* [a recent simple example](https://github.com/The-Strategy-Unit/nhp_analysis/pull/186) that explains what's changed, what needs checking and what it will close.
	* [one of many excellent PRs by Craig](https://github.com/The-Strategy-Unit/nhp_mitigator_comparisons_app/pull/98) that makes good use of sections, explanation and images, while also injecting some levity.
	* [a Copilot PR](https://github.com/The-Strategy-Unit/nhp_inputs/pull/591) that was created to test an LLM for adding boilerplate, which is well presented but perhaps overwhelming.

	## Going further

	We haven't talked about a lot of things, like:

	* submitting a PR [in someone else's repo](A slightly different approach ([using a 'fork'](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/proposing-changes-to-your-work-with-pull-requests/creating-a-pull-request-from-a-fork) using a fork
	* fixing [merge conflicts](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/addressing-merge-conflicts/resolving-a-merge-conflict-on-github) when your code changes clash with someone else's changes
	* adjusting commit history with [squash and rebase merges](https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/configuring-pull-request-merges/about-merge-methods-on-github)
	* using [GitHub Actions](https://docs.github.com/en/actions) to do things like run tests and checks on pull requests
	* not using the web interface, but using your IDE (e.g. [in VS Code](https://code.visualstudio.com/docs/sourcecontrol/github)) or [the GitHub command line interface](https://cli.github.com/)

	## Further reading

	There are lots of online resources, here's a few:

	* [Jack's code-review blog](https://jcken95.github.io/projects/code_review.html)
	* [The Tidyverse team's guide](https://code-review.tidyverse.org/)
	* [The SU Data Science website](https://the-strategy-unit.github.io/data_science/style/git_and_github.html#creating-and-reviewing-prs) (you can contribute!)