margin-docs/docs/release.md

# Releasing

## Installing locally

`just install` builds the app for whatever machine you are sitting at and installs it where that
machine expects to find applications: `/Applications` (or `~/Applications` when `/Applications`
is not writable) on macOS, the package manager or an AppImage plus a desktop entry on Linux. It is
the same command whether or not the app is already installed, so it doubles as the update. On
macOS it asks a running copy to quit first, because replacing a bundle under a live process leaves
it half old and half new. `just uninstall` reverses it and leaves the data directory alone.

The local build skips the dmg and builds only the `.app` on macOS, or the `.deb` and the AppImage
on Linux, since nothing about copying a bundle into place needs a disk image and building one is
the slowest part of a mac bundle. That makes a locally installed app slightly different from a
released one: it is ad hoc signed and carries no updater artifacts, so it will not update itself.
Rerun `just install`.

## Cutting a release

Releases are manual: run the Release workflow from the Actions tab. Leave the version empty to
bump the patch number, or give one to set it. The workflow bumps `tauri.conf.json`, `package.json`
and `src-tauri/Cargo.toml` together, commits that to main, tags it, and builds the tag rather than
whatever main happens to be by then.

It builds one universal macOS bundle and publishes nothing until it has landed. The last job
downloads `latest.json` and refuses to take the release out of draft unless three things hold: the
version in the manifest is the version in the tag, `darwin-aarch64` and `darwin-x86_64` are both
present, and each of them has a signature as well as a url. One universal build writes both of
those keys, pointing them at the same archive and the same signature, because an installed copy
asks the manifest for the architecture it is running on and never for a universal one. A
half-populated manifest is worse than no release at all: the updater would offer an update to the
platforms that made it and error on the ones that did not. A manifest carrying the version before
this one is worse again, because it tells everybody the copy they are already running is the newest
there is, and an entry with an empty signature is an update every installed copy downloads and then
refuses.

Linux is not built. It was until recently, because this pipeline was copied from margin-calendar,
which ships on Linux. This app does not, so the row and the manifest key it required are gone and
the release runs on one macOS runner.

Windows is not built. Nothing in `tauri.conf.json` targets it and the app has never claimed it.

## What the build needs

Two repository secrets sign the updater artifacts, so that an installed copy can tell a real update
from anything else offered at the same URL: `TAURI_SIGNING_PRIVATE_KEY` and
`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`. The public half lives in
`src-tauri/tauri.release.conf.json`, baked into every build, so the private half can never be
rotated without stranding everyone who has not updated yet; back up the key and its password
somewhere that is not the machine that generated them.

That file currently carries the placeholder `REPLACE_WITH_TAURI_SIGNER_PUBKEY`, and the keypair
behind it does not exist yet. Making it is a one-time step, run once by whoever owns the repository
and never again:

```
pnpm tauri signer generate -w ~/.tauri/margin-docs.key
```

It asks for a password, writes the private key to that path and the public key beside it as
`margin-docs.key.pub`, and prints both. The public one replaces the placeholder in
`tauri.release.conf.json` and is committed. The private one is the contents of
`~/.tauri/margin-docs.key`, pasted into `TAURI_SIGNING_PRIVATE_KEY`, with its password in
`TAURI_SIGNING_PRIVATE_KEY_PASSWORD`. Neither the key file nor the password goes into the
repository.

Six more secrets codesign and notarize the bundle, and unlike the two above they are optional as
far as the workflow is concerned: with none of them set the build still runs, still publishes, and
produces an ad hoc signed app. `APPLE_CERTIFICATE` is the Developer ID Application certificate
exported from Keychain Access as a `.p12` and base64 encoded (`base64 -i certificate.p12`), with
the password it was exported under in `APPLE_CERTIFICATE_PASSWORD`. `APPLE_SIGNING_IDENTITY` is the
certificate's full name, which looks like `Developer ID Application: Your Name (TEAMID)`. The other
three are for notarization: `APPLE_ID` is the Apple account's email address, `APPLE_PASSWORD` is an
app-specific password made at appleid.apple.com rather than the account password itself, and
`APPLE_TEAM_ID` is the ten character team identifier.

Those six are all or nothing. A repository with a certificate but no notarization credentials fails
the build rather than warning, because a signed bundle that has not been notarized is one Gatekeeper
refuses on any machine that has not seen it before, and finding that out from a user is worse than
finding it out from a red run.

The bundle asks for the hardened runtime, which notarization requires, and for no entitlements at
all. That is worth a sentence because it nearly went the other way. Deleting a document goes to the
Trash through the `trash` crate, whose macOS default is to ask Finder over an Apple event, and the
hardened runtime blocks an Apple event unless the bundle carries
`com.apple.security.automation.apple-events` and the user agrees to a permission prompt about
controlling Finder. `src-tauri/src/fs.rs` asks for `trashItemAtURL:` instead, which needs none of
that. The cost is Put Back, which the Finder method leaves on the file and this one does not; the
file is still in the Trash and can still be dragged out of it.

Beyond signing there is nothing to provision. Margin Docs talks to no external API and holds no
OAuth client, unlike margin-calendar, so there are no other repository secrets and nothing
equivalent to a `google-credentials.json` to embed at build time.

## Updates

Installed copies check
`https://github.com/priyanshujain/margin-docs/releases/latest/download/latest.json` and update
themselves from it. `--latest` on the publish step is what moves that pointer, so a release that
fails the manifest check stays a draft and no one is offered a broken update. The app checks that
URL once a day in the background and on the Check for Updates menu item, and either way what
happens next is a dialog rather than an install: the version, the release notes, the download with
a progress bar, and Later as a real answer.

Self-update does not work yet, and it will not until there is an Apple Developer ID certificate.
This is not a gap in the workflow, which is wired for one, or in the app, which is wired for the
whole flow. It is macOS: an update replaces the installed bundle with the downloaded one, and the
system will not let an ad hoc signed bundle take the place of a signed one, nor run a replacement
whose signature does not match what was there before. Every build this repository can currently
produce is ad hoc signed, so every self-update attempt ends in a bundle the system refuses to
launch. Until the certificate exists, updates are something to install by hand, and the honest
version of the feature is that the app will find the update, show it, download it, and fail on the
last step.

There is a second thing gated behind the same certificate. The build is not notarized either, so a
copy downloaded from the releases page is quarantined by the browser and refused on first launch
with the message about an unidentified developer. Both problems have the one fix.