From f5d5f5e6307220cad91577f0246e27039d20b022 Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?=E2=9C=A8=20Audrey=20=E2=9C=A8?= <audrey@audreyality.com>
Date: Thu, 26 Dec 2024 11:44:17 -0500
Subject: [PATCH] replace GPG signing recommendation with SSH

---
 docs/contributing/commit-signing.mdx | 39 ++++++++++++++--------------
 1 file changed, 19 insertions(+), 20 deletions(-)

diff --git a/docs/contributing/commit-signing.mdx b/docs/contributing/commit-signing.mdx
index bb4aed363..f46f303f0 100644
--- a/docs/contributing/commit-signing.mdx
+++ b/docs/contributing/commit-signing.mdx
@@ -22,33 +22,31 @@ their commits.
 ## Setting up commit signing
 
 Github supports commit signing with GPG, SSH and S/MIME. If you're unsure what to use, we recommend
-GPG.
+SSH.
 
-1.  Install GnuPG:
+1.  Follow the [Github documentation][github-verification] to configure commit signing
 
-  <Tabs groupId="os">
+2.  Configure your preferred git tool below
 
-    <TabItem value="mac" label="macOS">
-
-    ```bash
-    brew install gnupg
-    echo "export GPG_TTY=$(tty)" >> ~/.zshrc
-    ```
-
-    Restart your open terminal for this to take effect
-
-    </TabItem>
+3.  Push a test commit to Github and ensure that the "Verified" badge appears next to the commit
+    description:
 
-  </Tabs>
+    ![Image showing the Verified badge in Github](./commit-signing.png)
 
-2.  Follow the [Github documentation][github-verification] to configure commit signing
+:::tip
 
-3.  Configure your preferred git tool below
+We recommend you create a new commit signing key instead of reusing your Github authentication key,
+and that you protect the key with a strong passphrase or password.
 
-4.  Push a test commit to Github and ensure that the "Verified" badge appears next to the commit
-    description:
+```bash
+EMAIL=your.commit.email@example.com
+ssh-keygen -f ~/.ssh/bw-signing -C "$EMAIL" -t ed25519
+git.config --global user.email "$EMAIL"
+git config --global gpg.format=ssh
+git config --global user.signingkey=~/.ssh/bw-signing.pub
+```
 
-    ![Image showing the Verified badge in Github](./commit-signing.png)
+(Remove the `--global` flags to only apply this setting to the current repository) :::
 
 ### Command Line
 
@@ -58,10 +56,11 @@ GPG.
   git commit -S
   ```
 
-- To avoid using the `-S` flag every time, you can sign all commits by default:
+- To avoid using the `-S` flag every time, you can sign all commits and tags by default:
 
   ```bash
   git config --global commit.gpgSign true
+  git config --global tag.gpgSign true
   ```
 
   (Remove the `--global` flag to only apply this setting to the current repository)