macos: the pipeline is the project's, the identity is yours

Makefile.macos was kept out of git because it named a team, a person and
a mac. But almost all of it is mechanism -- build, sign, zip, notarize,
staple, unlock a headless keychain -- and that is the project's, not the
releaser's. Keeping the whole file out to protect four values meant the
one machine that had it was the only place a release could be cut from,
and that nobody could read how signing worked without being handed it.

So the split is inverted. Makefile.macos, the builder doc and the scripts
are tracked; macos-release.mk holds TEAM_ID, SIGNER and BUILDER and is
the only thing gitignored. macos-release.mk.example is the template.

The identity strings are now assembled from SIGNER and TEAM_ID rather
than written out, which means an unconfigured checkout composes
"Developer ID Application:  ()" -- plausible, wrong, and diagnosed only
by codesign a minute into a build. require-identity and require-builder
catch it before anything runs and name the file to create; `help` prints
"(unset)" rather than the empty shape.

macos-remote-build now pushes macos-release.mk instead of Makefile.macos.
That is the better arrangement anyway: the builder gets its pipeline from
git at the commit being released, so a release is signed by the flow
belonging to it and not by whatever the laptop was carrying.

MACOS-BUILDER.md was in the same position -- local, and referenced by a
file that is now tracked -- so it becomes docs/macos-release.md with the
certificate name and notary key id replaced by their shapes.

1 files changed, 53 insertions, 0 deletions

diff --git a/macos-release.mk.example b/macos-release.mk.example
new file mode 100644
index 0000000..930e0df
--- /dev/null
+++ b/macos-release.mk.example
@@ -0,0 +1,53 @@
+# slosh — who signs the macOS builds, and on which mac.
+#
+# Copy this file to `macos-release.mk` and fill it in. That copy is gitignored:
+# it is the *only* place the release flow keeps anything specific to you, which
+# is what lets Makefile.macos and the contrib/ scripts live in the repo.
+#
+#     cp macos-release.mk.example macos-release.mk
+#     $EDITOR macos-release.mk
+#     make macos-dist
+#
+# Nothing secret goes in here. The signing key lives in a keychain on the
+# builder and the notarization credential is a keychain profile; neither is a
+# value you could paste. This file only says *which* key and *which* mac.
+#
+# It is included by Makefile.macos, so it is make syntax: no quotes, and a
+# value runs to the end of the line (trailing spaces included — do not add
+# any after a name).
+
+# ── Apple ───────────────────────────────────────────────────────────────────
+# Your Developer Program Team ID: ten alphanumerics, shown at
+# developer.apple.com/account under Membership.
+TEAM_ID = XXXXXXXXXX
+
+# The name Apple issued the certificate to, exactly as it appears there. It is
+# the middle of the identity string, and this prints the whole thing:
+#
+#     security find-identity -v -p codesigning
+#     1) A1B2...  "Developer ID Application: Your Name (XXXXXXXXXX)"
+#                                            ^^^^^^^^^ this part
+#
+# A team certificate is issued to the organisation, so that name goes here
+# instead of a person's.
+SIGNER = Your Name
+
+# ── the builder ─────────────────────────────────────────────────────────────
+# The mac that holds the private key, as an ssh host — a `Host` entry in
+# ~/.ssh/config, or user@host. It does not have to be, and normally is not,
+# the machine you develop on. contrib/macos-builder-setup provisions it.
+BUILDER = m1
+
+# Where the checkout lives on the builder. The default suits what
+# macos-builder-setup creates; uncomment only to point somewhere else.
+#BUILDER_DIR = src/slosh
+
+# ── optional ────────────────────────────────────────────────────────────────
+# Only used to print a copy-pasteable command in `make -f Makefile.macos
+# setup-notary`. The credential itself is stored in the keychain, not here.
+#APPLE_ID = you@example.com
+
+# The identity strings are assembled from SIGNER and TEAM_ID. Set them
+# outright only if your certificate's common name is not the usual shape.
+#IDENTITY = Developer ID Application: Your Name (XXXXXXXXXX)
+#INSTALLER_IDENTITY = Developer ID Installer: Your Name (XXXXXXXXXX)