docs: add signing identity examples and link to how-to guides

changes/2627.misc.md

@@ -0,0 +1 @@
+Details on the format of the `-i` argument have been added.

docs/en/how-to/building/ci.md

@@ -62,7 +62,7 @@ This workflow should be saved in to a file at `.github/workflows/ci.yml` in your
 
 ## Limitations of Uploaded Artefacts
 
-The artefacts produced and uploaded by this workflow will not be signed; therefore, when the app is executed locally, some platforms may show a disconcerting warning about the security of the app or prevent the app from running altogether. See more information about code signing in the [identity guides][obtaining-a-code-signing-identity].
+The artefacts produced and uploaded by this workflow will not be signed; therefore, when the app is executed locally, some platforms may show a disconcerting warning about the security of the app or prevent the app from running altogether. See more information about code signing in the [identity guides][obtain-code-signing-identity].
 
 ## Workflow File Contents
 

docs/en/how-to/index.md

@@ -2,7 +2,7 @@
 
 How-to guides are recipes that take the user through steps in key subjects. They are more advanced than tutorials and assume a lot more about what the user already knows than tutorials do, and unlike documents in the tutorial they can stand alone.
 
-## Obtaining a Code Signing identity
+## Obtaining a Code Signing identity { #obtain-code-signing-identity }
 
 * [Android](code-signing/android.md) - One way to sign your app where the Google Play Store maintains the authoritative key for your app.
 * [macOS](code-signing/macOS.md) - How to generate a macOS code signing identity, which is required to distribute your application.

docs/en/reference/commands/package.md

@@ -59,4 +59,10 @@ Perform the bare minimum signing that will result in a app that can run on your
 
 ### `-i <identity>` / `--identity <identity>`
 
-The [code signing identity][how-to] to use when signing the app.
+The [code signing identity][obtain-code-signing-identity] to use when signing the app.
+
+The format for the code signing identity is platform specific:
+
+* **On macOS:** The 40-character hex thumbprint of the signing identity; the full name of the certificate (e.g., `Developer ID Application: Jane Smith (ABC12345DE)`); or `-` to use an ad-hoc signature. See the [documentation on macOS code signing for more details](../../how-to/code-signing/macOS.md).
+
+* **On Windows:** The 40-character hex thumbprint of the signing identity; or the subject name of a certificate in the user's certificate store. See the [documentation on Windows code signing for more details](../../how-to/code-signing/windows.md).