Merge pull request #975 from alphagov/pair-programming-coauthoredby

BAU: Add section on using Co-authored-by when pairing

.github/workflows/test.yaml

@@ -18,7 +18,7 @@ jobs:
         fetch-depth: 0 # Fetch entire history, because the check_links.rb script relies on it
 
     - name: Set up Ruby
-      uses: ruby/setup-ruby@22fdc77bf4148f810455b226c90fb81b5cbc00a7 # v1.171.0
+      uses: ruby/setup-ruby@4a9ddd6f338a97768b8006bf671dfbad383215f4 # 1.207.0
       with:
         bundler-cache: true
 

source/standards/pair-programming.html.md.erb

@@ -71,6 +71,25 @@ This has several benefits, such as:
 
 However, teams should adjust their policy on this approach depending on the risk tolerance of the codebase, team, or programme.
 
+## Pair programming and version control
+
+Almost all version control systems, including Git, are oriented around a single-author-per-change model. This doesn't completely align with collaborative development practices.
+
+A convention has emerged, and is supported by GitHub, to use the [`Co-authored-by`](https://docs.github.com/en/pull-requests/committing-changes-to-your-project/creating-and-editing-commits/creating-a-commit-with-multiple-authors) trailer on commit messages to flag that multiple people have worked on a change.
+
+For example, if you had two or more contributing as part of a pair or ensemble, you would structure your commit message like:
+
+```
+TICKET-123: Add a new feature
+
+Co-authored-by: [email protected]
+Co-authored-by: [email protected]
+```
+
+This is visible within the normal Git log and within GitHub too; you will see multiple people attached to a change in the UI.
+
+You should use your work email address in the `Co-authored-by` trailer.
+
 ## Further reading
 
 - Pairing and code review guidelines for [GOV.UK Pay](https://manual.payments.service.gov.uk/manual/development-processes/pairing-principles.html)