adding notes around retrospectively signing commits (#345)

Author: walteck

images/commit-history-github.png

@@ -179,3 +179,5 @@ git push
 Re-run your git command prefixed with GIT_TRACE=1
 
 A failure to sign a commit is usually because the name or email does not quite match those which were used to generate the GPG key, so git cannot auto-select a key. Ensure that these are indeed consistent. (If you added a comment when creating your gpg key, this *may* cause a mismatch: the comment will be visible when listing your gpg keys, e.g. `RealName (Comment) <EmailAddress>`.) You are able to [force a choice of signing key](https://docs.github.com/en/authentication/managing-commit-signature-verification/telling-git-about-your-signing-key), though this should not be necessary.
+
+If you have already committed and need to retrospectively sign this commit [please follow the instructions here](./retrospective-commit-signing.md).

images/cycle-through-flagged-commits.png

@@ -0,0 +1,77 @@
+# Retrospective commit signing guide
+
+- [Retrospective commit signing guide](#retrospective-commit-signing-guide)
+  - [Signing previously pushed commits](#signing-previously-pushed-commits)
+    - [Steps](#steps)
+
+## Signing previously pushed commits
+
+If you have pushed a commit without signing this can result in your PR not being able to be merged into the main or default branch. The following steps will guide you through retrospectively signing your commits. Note you can sign multiple commits if required.
+
+Please take the time to understand the commands that you are using, this is just a guide.
+
+### Steps
+
+1. **Identify unsigned commits**  
+   You have a branch that contains one or more unsigned commits. In the screenshot below, there are two unsigned commits followed by two commits showing the `Verified` label, which indicates they were signed.
+
+   ![Commit history showing unsigned and signed commits](../../images/commit-history-github.png)
+
+2. **Understand the issue**  
+   The first two commits aren't verified, and therefore the merge to the `main` branch is not allowed:
+
+   ![Merging is blocked as the commits aren't signed](../../images/merging-is-blocked-signatures.png)
+
+3. **Switch to the branch with unsigned commits**  
+   Go to your CLI and ensure that you are on the branch with the unsigned commits.
+
+4. **Start an interactive rebase**  
+   Issue the following command:
+
+   ```bash
+   git rebase -i --root
+   ```
+
+   This puts the editor into interactive mode for rebase. You will see the commit history as shown in the screenshot below:
+
+   ![Interactive rebase before selecting commits](../../images/interactive-rebase-before-selecting-commits.png)
+
+5. **Mark commits for editing**  
+   Scroll down the list until you find the commits you want to sign. Change the keyword `pick` to `edit` for those commits.
+
+   ![Interactive rebase after selecting commits](../../images/interactive-rebase-after-selecting-commits.png)
+
+   If you are using `Nano`, save the changes with `Ctrl+X` and confirm with `Enter`. For `Vi`, exit with `:wq` to save and quit.
+
+6. **Amend the commit to include a signature**  
+   For each commit you flagged as `edit`, run the following commands:
+
+   ```bash
+   git commit -S --amend --no-edit
+   git rebase --continue
+   ```
+
+   Rebase will cycle through the commits you flagged for editing:
+
+   ![Cycling through commits flagged for editing](../../images/cycle-through-flagged-commits.png)
+
+   Repeat the `amend` and `continue` steps for each commit.
+
+7. **Complete the rebase**  
+   Once rebasing is complete, you will see a message like:
+
+   ```plaintext
+   Successfully rebased and updated refs/heads/…
+   ```
+
+8. **Push the changes**  
+   Push the updated commits back to your branch. Use a force push if necessary:
+
+   ```bash
+   git push -f
+   ```
+
+9. **Verify the changes**  
+   Refresh the browser window for your PR. You should now see the verified commits:
+
+   ![Updated commit history in GitHub](../../images/updated-commit-history-github.png)

images/interactive-rebase-after-selecting-commits.png

@@ -155,7 +155,9 @@
 
 ### Browser/OS testing guidance
 
+<!-- markdown-link-check-disable -->
 - Website user interfaces should be tested against an appropriate set of browsers and versions &mdash; in particular, no effort should be spent testing against unsupported browsers or unsupported versions of browsers. See supported browsers for [Staff](https://aalto.digital.nhs.uk/#/document/viewer/8c039de1-eec0-49cd-8af3-a97fed6a8bff?library=5464c07f-daf1-4eee-b9b6-22e6c4dfbbd0) and [Citizens](https://aalto.digital.nhs.uk/#/document/viewer/465e6d1b-f107-49eb-ad25-e72c0299d3a6?library=5464c07f-daf1-4eee-b9b6-22e6c4dfbbd0)
+<!-- markdown-link-check-enable -->
 
 ## Other tools to consider