Releasing

A release has to be checkable byte for byte by anyone: its checksums, its signature, and the match between the source archive and the tag. These are the steps a maintainer follows.

Version numbers

Three parts, major.minor.patch. When a file format read or written, or the command line’s output format, changes, the minor version goes up and the release notes list the change; a release of defect fixes alone raises the patch number. The law’s version is written in its spec name and is independent of the software version.

Before a release

• Every test passes on main, on each released system.
• Both digests of the law recompute to their values.
• The cores show zero divergences against the frozen cores, and every chain-facing recording replays identically.
• The contract’s code hash recomputes correctly.
• The Chinese and English manuals match the interface sentence for sentence.
• The six first-launch steps are walked through on a clean machine.
• One upgrade and one restore are done with a data folder and a backup from the previous version.
• A whole-machine backup exported on one system is restored once on each of the others.

Build

Release files are built from the tagged commit. The macOS packages come from the packaging script, with the signing identity:

The script builds the app and the command line with --locked, puts the window program zikaron-desk and the command line zikaron into ZIKARON.app, signs and verifies each one, then makes dist/ZIKARON-<version>-macos-<arch>.dmg (with a link to Applications) and a .pkg (the app into /Applications, the command line into /usr/local/bin), and writes SHA256SUMS-macos-<arch>.txt. Binaries are stripped of symbols; the home, source and build directory paths are mapped away at compile time, so the product is independent of the build machine. The Linux .deb and AppImage come from packaging/linux/build.sh, or from cross-build.sh on another host.

Checksums and Zikaron record

1. Compute the SHA-256 of every release file (each platform’s packages and the source archive) and gather them into one release list, SHA256SUMS.txt.
2. At commit time, record the commit in the project’s Zikaron ledger, together with each release file’s fingerprint, and anchor them on chain; the release notes state the transaction, block, recorder address and each fingerprint.
3. The release page, the website’s download page and the list agree in all three places; the download page’s “Zikaron record” column carries each file’s anchoring transaction.

How users check them is under Checksums.

System signing

The app and the dmg are signed with the project’s own certificate, whose common name is Kaptonia; the project issues this certificate itself, the release is outside Apple’s notarization, and the project publishes it directly. Every version is signed with the same certificate and the same identifier, com.kaptonia.zikaron.app, so the system recognizes each version as the same app. The pkg is checked by its SHA-256.

Files downloaded in a browser carry a quarantine flag, and macOS refuses to open them; on recent macOS, “Open Anyway” works only some of the time. The way the download page and the release notes give is: check the file with shasum -a 256 first, then remove the quarantine flag in Terminal with xattr. Users who want to confirm where a file came from can check its signer, certificate fingerprint, checksum and Zikaron record; see Checksums.

Release notes

For every version, state what was added, changed and fixed; changes to file formats and command-line output; and what users have to do when upgrading. State what holds now.

Contract and networks

The app carries a table of known deployments: chain ID, registry contract address, start block, default nodes. Before adding a row:

1. Read the code from the chain and check its code hash.
2. Confirm that the start block comes before the first anchor on that contract.
3. Choose two default nodes from different sources, both with TLS, both answering the right chain ID.

Rows are only added; released rows stay as they are, and old ledgers go on being verified by them.

The website

With every version the website updates the file names, sizes, checksums and Zikaron records on its download page. The pages are generated by a script in the repository, and the output is committed with it.

After a release

• Download a copy from the release page, then check, install and open it by the users’ own steps.
• Confirm that the drop zone on the download page answers “Matches the release list” for every file.
• When a release file turns out to be wrong, publish a new patch version; published files and checksums stay as they are.