matt-dray · November 6, 2025 14:41 · Nov 6, 2025 · Nov 6, 2025 · Nov 6, 2025 · Nov 6, 2025
diff --git a/20251106_coffee_github-pr.txt b/20251106_coffee_github-pr.txt
@@ -68,7 +68,7 @@ As the reviewer, I should:
 
 * read the story, ask for more information if needed
 * explain what I checked, what I found and give advice
-* nitpick sensibly (e.g. are you forcing a minor personal preference?)
+* 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

diff --git a/20251106_coffee_github-pr.txt b/20251106_coffee_github-pr.txt
@@ -2,8 +2,8 @@
 
 ## Focus
 
-This is about using the GitHub interface for pull requests (PRs) from the perspective of the assignee (submitter) and reviewer.
-It's about submitting [a pull request](https://docs.github.com/en/pull-requests) to a repository that you have access to, e.g. in The-Strategy-Unit org.
+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?
 
@@ -17,11 +17,14 @@ Pull requests are important because they help:
 
 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 get.
+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!
 
@@ -56,19 +59,17 @@ So:
 
 As the assignee (submitter), I should:
 
-* not commit directly to main
+* raise PRs and not commit directly to main
 * keep my PR small in code/commits and solve one issue
-* assign myself, choose a reviewer
-* explain: what issue will close, what have I changed, any special instructions?
+* 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 and what I found
+* read the story, ask for more information if needed
+* explain what I checked, what I found and give advice
 * nitpick sensibly (e.g. are you forcing a minor personal preference?)
-* be nice
+* be nice: consider the context of the assignee and the 'importance' of the PR
 
 ## Examples
 

diff --git a/20251106_coffee_github-pr.txt b/20251106_coffee_github-pr.txt
@@ -90,6 +90,8 @@ We haven't talked about a lot of things, like:
 
 ## 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!)
diff --git a/20251106_coffee_github-pr.txt b/20251106_coffee_github-pr.txt
@@ -17,7 +17,7 @@ Pull requests are important because they help:
 
 It's a stop-and-breathe opportunity during the coding process.
 
-## Cautionwhy pull request
+## Caution
 
 Every PR is different.
 Sometimes it's a single typo, sometimes it's adding a feature.

diff --git a/20251106_coffee_github-pr.txt b/20251106_coffee_github-pr.txt
@@ -67,7 +67,7 @@ As the reviewer, I should:
 * read the story
 * ask for more information if needed
 * explain what I checked and what I found
-* nitpick sensibly (e.g. 'consider a spellcheck' rather than correcting )
+* nitpick sensibly (e.g. are you forcing a minor personal preference?)
 * be nice
 
 ## Examples

diff --git a/gistfile1.txt → 20251106_coffee_github-pr.txt b/gistfile1.txt → 20251106_coffee_github-pr.txt
@@ -1,4 +1,4 @@
-# The Strategy Unit C&C, 2025-11-06: 
+# The Strategy Unit C&C, 2025-11-06: collaborating using Github
 
 ## Focus
 

diff --git a/gistfile1.txt b/gistfile1.txt
@@ -0,0 +1,95 @@
+# The Strategy Unit C&C, 2025-11-06: 
+
+## Focus
+
+This is about using the GitHub interface for pull requests (PRs) from the perspective of the assignee (submitter) and reviewer.
+It's about submitting [a pull request](https://docs.github.com/en/pull-requests) to a repository that you have access to, e.g. in The-Strategy-Unit org.
+
+## 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.
+
+## Cautionwhy pull request
+
+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 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:
+
+* not commit directly to main
+* keep my PR small in code/commits and solve one issue
+* assign myself, choose a reviewer
+* explain: what issue will close, 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 and what I found
+* nitpick sensibly (e.g. 'consider a spellcheck' rather than correcting )
+* be nice
+
+## 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
+
+* [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!)
No results found