# PR#118: Werkator Releases werkrevisor After Each Merge

Version: minor

> **WARNING:** This document describes only the change applied in this PR.
> It may already be outdated once the next PR is merged.
> Historic PR documentation is not maintained along with new PRs; treat it as a snapshot.

## Related Links

- [werkrevisor PR#115](https://git.javagil.de/mi/werkrevisor/pulls/115): `tools/build-rootfs` with Podman.

## Problem

A merge to `main` does not reach mih09.
The human builds the rootfs archive on the workstation with `tools/build-rootfs`
and distributes it with `tools/deploy-rootfs`; until then, the reviews run the old version.
mih09 has neither Docker nor Podman, so Werkator cannot run `tools/build-rootfs` there.

## Non-Goals

- No automatic release of the statistics service.
- No automatic update of the PR-Agent base image; a new base image stays a manual step.

## Specification

### Feature: a merge to main releases werkrevisor

#### Scenario#118.01: a new version is assembled and installed

… so that the reviews run the merged code without a manual step.

- **Given** `main` at a version whose archive does not exist yet, and the base archive of the pinned PR-Agent image
- **When** the release build runs after the green build of `main`
- **Then** the archive of the version holds the base archive plus `werkrevisor/werkrevisor/` and `werkrevisor/config/`,
  and each machine config that named a werkrevisor archive names the new one

##### Verified by

- [test_release_rootfs.ReleaseRootfsTest.test_a_new_version_is_assembled_and_installed](../../tests/test_release_rootfs.py)

#### Scenario#118.02: a released version is not released again

… so that a repeated build changes nothing.

- **Given** every machine config names the archive of the current version
- **When** the release build runs
- **Then** it builds nothing, changes no machine config and succeeds

##### Verified by

- [test_release_rootfs.ReleaseRootfsTest.test_a_released_version_is_not_released_again](../../tests/test_release_rootfs.py)

#### Scenario#118.03: a missing base archive fails the release

… so that a new PR-Agent image is not released with the files of the old one.

- **Given** the base archive of the PR-Agent image named in the `Dockerfile` is missing
- **When** the release build runs
- **Then** it fails, names the missing archive and the command that creates it, and changes no machine config

##### Verified by

- [test_release_rootfs.ReleaseRootfsTest.test_a_missing_base_archive_fails_the_release](../../tests/test_release_rootfs.py)

#### Scenario#118.04: a machine config without a werkrevisor archive stays unchanged

… so that a repository without werkrevisor reviews does not get one.

- **Given** a machine config that names no werkrevisor archive
- **When** the release build installs a new version
- **Then** that machine config is unchanged and has no backup

##### Verified by

- [test_release_rootfs.ReleaseRootfsTest.test_a_machine_config_without_a_werkrevisor_archive_stays_unchanged](../../tests/test_release_rootfs.py)

## Solution

- `tools/release_rootfs.py release` is the build command of the new build `release` in `.werkator.yml`.
  It reads the version and assembles `werkrevisor-rootfs-<version>.tar.zst` with Python's `tarfile`:
  the base archive `pr-agent-rootfs-<digest>.tar.zst`, plus `/work`, `werkrevisor/werkrevisor/` and `werkrevisor/config/`,
  owned by root, without `__pycache__`.
  Its file list equals the one of the archive 0.44.1, plus `/work`, the `WORKDIR` of the `Dockerfile`:
  the Docker build of 0.43.0 holds it, the Podman build of 0.44.1 does not.
  The reviews run in the worktree and do not use `/work`; the archive holds it so that it matches the `Dockerfile`.
- It compresses with `compression.zstd`, part of the standard library since Python 3.14 (PEP 784),
  else with the `zstd` program; mih09 has Python 3.11.
- It replaces each machine config through a temporary file with the same mode, so Werkator never reads half of one.
- It refuses to install if a machine config names a werkrevisor archive in another directory,
  since only the name of the archive changes.
- The base archive carries the first 12 hex digits of the digest in the `Dockerfile`;
  a new PR-Agent image needs a new base archive, which `tools/build-rootfs --base` creates on the workstation.
- `tools/release_rootfs.py install` replaces the remote script of `tools/deploy-rootfs`, so both ways install alike.
  Without repositories it takes each machine config that names a werkrevisor archive,
  and the release build takes the directory of these archives; so no list of repositories needs care.
- The trigger `afterSuccessOf: default` on `main` and the native runtime are the host's part, pinned by Werkator.
  The build runs outside the sandbox, since the sandbox sees neither the machine configs nor `/home/storage`.
- `.werkrevisor.toml` lets Jev judge `tools/deploy-rootfs` and `tools/release_rootfs.py` like `tools/build-rootfs`.
- README, operations document and AGENTS.md describe the release build.
- Version 0.46.0; PR#117 holds 0.45.0.

### Setup on mih09 after the merge

1. Copy `pr-agent-rootfs-7d98954c2928.tar.zst` to `/home/storage/mih09/users/werkator/`.
2. Add the host part of `release` to `~/werkrevisor/.git/werkator/.werkator.yml`, as in the README.
3. Check that the release build of the merge commit installs 0.46.0.

## Open Questions

None.

## Follow-up PRs

- Once werkdock builds images, the release build may build from the `Dockerfile` and drop the base archive.