1---2title: "Releasing"3sidebar_position: 84---56# Releasing78A release is an annotated version tag whose message is the release9notes, and archives of the binaries built from it on a maintainer's10machine, served with the docs site at11[012.dev.site](site.md#where-it-lives) along with the install scripts12that download them. The GitHub repository only13hosts the code: nothing builds or publishes there.1415## Checklist1617The steps in order, and what each leaves behind; a small release may18skip the stress run:1920```mermaid21flowchart TD22 check[make check, the gallery reviewed] --> small{a small release?}23 small -->|no| stress[make stress, make stress-report]24 small -->|yes| xlsx25 stress -->|the run recorded on the commit| xlsx[XLSX opened in Excel, LibreOffice, Sheets]26 xlsx --> fixtures[this release's file fixtures committed]27 fixtures --> tag[git tag -a, git push]28 tag -->|the module proxy| install[go install ...@v1.2.3]29 tag --> dist[make dist]30 dist --> archives[dist/: archives, SHA256SUMS]31 archives --> publish[make site-publish]32 publish --> live[install.sh, /releases/v1.2.3/ and /releases/latest/ live]33```34351. **`make check`** passes on the commit to be tagged (see36 [Testing](testing.md)), with the golden screens reviewed in the37 gallery.382. **Stress** (optional for small releases): `make stress` on a quiet39 machine, then `make stress-report`, which compares the run with the40 last release's and exits non-zero on a regression past the threshold41 (see [Observability](observability.md#regressions-against-the-last-release)).42 Record the run on the release commit so the next release compares43 against it.443. **XLSX in spreadsheet apps.** Export a workbook that uses what the45 release touches (formats, notes, frozen panes, filters, validation,46 conditional formats, charts' data) with File > Download, and open it in47 Excel, LibreOffice Calc and Google Sheets: it opens without a repair48 prompt, and values, formulas and formats read as they did in 012. The49 automated checks read XLSX with excelize and 012's own reader only.504. **File fixtures**: the workbooks this release saves, committed (see51 [File fixtures](#file-fixtures)).525. **Tag** with the release notes as the message, what changed since the53 previous tag for a user, with the install line last:5455 ```sh56 git tag -a v1.2.3 # the editor opens for the notes57 git push origin v1.2.358 ```5960 The Go module proxy picks the tag up, so `go install61 src.rest/cat/012/cmd/012@v1.2.3` works from then on.626. **Binaries**: `make dist VERSION=v1.2.3` on the tagged commit.637. **Publish** the site with the release64 ([Publishing](#publishing)):6566 ```sh67 make site-publish VERSION=v1.2.368 ```6970 then check the live copy: `SHA256SUMS` at71 `https://012.dev.site/releases/v1.2.3/` matches `dist/SHA256SUMS`, and72 `curl -fsSL https://012.dev.site/install.sh | PREFIX=$(mktemp -d) sh`73 installs a `012` whose `012 version` prints v1.2.3.7475## File fixtures7677`internal/sheet/testdata/fixtures` holds workbooks as each release saved78them, a folder per release (`v0.2.0/`), and79`TestFixturesOpenAndSaveUnchanged` opens every one and saves it again,80failing unless the bytes come back the same. A later build that can't81open a release's file, or saves it differently, fails `make check`82([The .012 format](../files/format.md#versions) says what that83promises).8485The workbooks a release saves are the ones in `fixtures/new`, written by86hand to use everything the format stores: formats, entries that read87against their format, column and row formats, widths, heights, merges,88borders, freeze, filters, names, notes, protection, rules and89validation, charts, pivot tables, a notebook tab's cells and outputs,90outputs sent to a sheet, linked files, macros, the locale and decimal91arithmetic. A release that adds to the format adds what it adds there.92Then, on the commit to be tagged:9394```sh95go test ./internal/sheet -run TestFixtures -fixtures v1.2.396```9798saves them with that build into `fixtures/v1.2.3`, to commit with the99release. The test refuses a folder that exists. A released folder is100never edited or replaced: when a later build saves one differently, the101build is what changes. The folder of a release not yet tagged may be102deleted and saved again.103104## make dist105106`make dist VERSION=v1.2.3` (`scripts/dist.sh`) cross-compiles 012 with107`CGO_ENABLED=0` and `-trimpath` for macOS, Linux and Windows on amd64108and arm64, stamping the version with `-ldflags -X main.version=...`, so109`012 version` prints it. Each platform gets an archive in `dist/`110(gitignored) holding the binary, `LICENSE`, `NOTICE` and `README.md`:111112```113dist/012_1.2.3_darwin_arm64.tar.gz114dist/012_1.2.3_linux_amd64.tar.gz115dist/012_1.2.3_windows_amd64.zip116...117dist/SHA256SUMS118```119120`PLATFORMS="darwin/arm64 linux/amd64"` narrows the list. The script121refuses a version that isn't `vMAJOR.MINOR.PATCH` (with an optional122`-suffix`) or that is tagged at another commit than the one checked123out, and warns when the tree has uncommitted changes. The archives and124`SHA256SUMS` are what a release publishes.125126## Publishing127128`make site-release` (`scripts/site-release.sh`) builds the docs site as129`make site` does and adds the release to `website/build`:130131```132website/build/install.sh133website/build/install.ps1134website/build/releases/v1.2.3/ archives, SHA256SUMS, an index page135website/build/releases/latest/ the same files136```137138`VERSION` defaults to the newest version tag. The archives are `dist/`'s139when its `SHA256SUMS` names that version; otherwise the script checks140the tag out in a temporary git worktree, runs `make dist` there and141keeps the result in `dist/`, so the site can be published from a commit142after the tag. It checks the archives against `SHA256SUMS` before143copying them. `SITE_URL` also goes into the copied install scripts, so a144site built for another address serves scripts that download from it.145146The site serves one release, `VERSION`, under both addresses; earlier147releases stay installable with `go install ...@v1.2.3`.148`make site-publish` deploys the result149([The docs site](site.md#where-it-lives)). Every deploy replaces the150whole site, so the docs are always published with the release: a151deploy of a plain `make site` build leaves the install script without152its archives.153154The install scripts live in `scripts/install/`. `install.sh` is POSIX155sh (it runs under dash as well as sh) and needs curl or wget, tar, and156sha256sum, shasum or openssl. `install_test.go`, in `make test`, runs157it as a file and piped to the shell against a local server holding a158fake release: the latest into `~/.local/bin`, a version under `PREFIX`,159and a refusal of an archive whose checksum doesn't match. `install.ps1`160has no automated test, as no PowerShell is assumed on a maintainer's161machine; try it on Windows when it changes.