Skip to content

Commit 8c6b895

Browse files
Vonngclaude
Vonng
and
claude
committed
docs: publish Farrow 0.4.0
Release post (en/zh), Status header and history entry for the v0.4.0 tag commit, tutorial install lines, 0.3.0 post marked superseded, plus the 0.4.0 behavior changes: fs auto default, up runs setup on a fresh host, readiness detail messages. Co-Authored-By: Claude Fable 5.1 <noreply@anthropic.com> Claude-Session: https://claude.ai/code/session_01T5xLYttkQWBbd2BTX1j1W7
1 parent 5fa7199 commit 8c6b895

12 files changed

Lines changed: 199 additions & 38 deletions

‎content/blog/release/farrow-0.3.0.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@ title: "Farrow 0.3.0: explicit catalogs and actionable readiness"
33
linkTitle: Farrow 0.3.0
44
description: Explicit image-catalog updates, per-node bootstrap diagnostics, native guest interface names, and a smaller CLI.
55
date: 2026-09-02
6-
weight: 1
6+
weight: 2
77
categories: [Release]
88
tags: [Farrow 0.3.0, QEMU, Catalog, Readiness, Release]
99
icon: fa-solid fa-rocket
1010
---
1111

12-
Farrow 0.3.0 is the current public pre-1.0 release. It removes implicit
12+
Farrow 0.3.0 was the public pre-1.0 release superseded by 0.4.0. It removes implicit
1313
Catalog refreshes, turns guest bootstrap failures into actionable per-node
1414
results, and simplifies the CLI without changing the Pigsty Inventory or
1515
fixed-IP deployment model.

‎content/blog/release/farrow-0.3.0.zh.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -3,13 +3,13 @@ title: "Farrow 0.3.0：显式 Catalog 与可操作的就绪诊断"
33
linkTitle: Farrow 0.3.0
44
description: 显式镜像 Catalog 更新、逐节点 Bootstrap 诊断、发行版原生 Guest 网卡名与更小的 CLI。
55
date: 2026-09-02
6-
weight: 1
6+
weight: 2
77
categories: [发布]
88
tags: [Farrow 0.3.0, QEMU, Catalog, 就绪, 发布]
99
icon: fa-solid fa-rocket
1010
---
1111

12-
Farrow 0.3.0 是当前公开的 pre-1.0 发布。它移除隐式 Catalog 刷新，把 Guest Bootstrap
12+
Farrow 0.3.0 是被 0.4.0 取代的公开 pre-1.0 发布。它移除隐式 Catalog 刷新，把 Guest Bootstrap
1313
失败变成可操作的逐节点结果，并在不改变 Pigsty Inventory 与固定 IP Deployment 模型的
1414
前提下简化 CLI。
1515

‎content/blog/release/farrow-0.4.0.md‎

Lines changed: 75 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,75 @@
1+
---
2+
title: "Farrow 0.4.0: one command, working data disks, one voice"
3+
linkTitle: Farrow 0.4.0
4+
description: A first run that is one command, a default data disk that works on every image, readiness failures that name the cause, and one output style across the CLI.
5+
date: 2026-09-02
6+
weight: 1
7+
categories: [Release]
8+
tags: [Farrow 0.4.0, QEMU, UX, Release]
9+
icon: fa-solid fa-rocket
10+
---
11+
12+
Farrow 0.4.0 is the current public pre-1.0 release. It makes the first run one
13+
command, fixes the default data disk on Debian and Ubuntu images, and gives every
14+
command the same output style. The Pigsty Inventory format, the fixed-IP
15+
deployment model, the state layout, and the embedded Catalog revision
16+
`2026082903` are unchanged.
17+
18+
## What changed
19+
20+
- On a terminal, `farrow up` runs `farrow setup` itself when the fixed-IP
21+
network has never been installed, shows the setup plan, asks before the
22+
privileged step, and then continues. `farrow init` points at `farrow up`.
23+
- `vm_disks[].fs` defaults to `auto`: a blank disk is formatted XFS when the
24+
guest has `mkfs.xfs` and ext4 otherwise, the same choice Pigsty's Vagrant flow
25+
makes. The old `xfs` default failed on Debian and Ubuntu images, which ship
26+
without xfsprogs. Deployments created with the old default are not reported
27+
as drift and their persistent disks stay compatible.
28+
- The guest error marker carries the failing command's last message, so `up`
29+
reports `guest bootstrap failed during data-disks: xfs requested but mkfs.xfs
30+
is unavailable` instead of an exit status.
31+
- Lifecycle commands and `status` print a node table and, after `up`, a
32+
`next: farrow ssh <node>` hint. `plan` and `validate` print one line when
33+
nothing changes; `image list`, `network status`, `doctor`, and preflight
34+
errors use plain sentences without machine codes; `spec hash` and other
35+
internals moved to `--json`. Errors about an unknown node list the nodes.
36+
- `farrow ssh <node> -- 'df -h /data; id'` passes the remote command exactly as
37+
OpenSSH does.
38+
39+
## Upgrading
40+
41+
A d13, d12, or Ubuntu node created by 0.3.0 or earlier whose `/data` never
42+
mounted needs one `farrow recreate <node>`; the disk is then formatted ext4 on
43+
those images and XFS on Enterprise Linux images. Automation that runs `up` on an
44+
unprepared host without a terminal still needs `farrow setup --yes` first.
45+
46+
## Verification boundary
47+
48+
Source commit `8ecb8476c7dbc934d8cbbee935ac53884d00fcdb` passed the complete
49+
local source gate: unit and race tests, vet, Staticcheck, deadcode, errcheck,
50+
`govulncheck`, shell and module checks, four target builds, the image-pipeline
51+
and installer boundaries, and dependency licenses. The tag workflow repeated
52+
those checks and built and verified every archive, native package, SBOM, and
53+
the installer before the Release was made public.
54+
55+
The new first-run path (`up` running `setup`) is covered by unit tests and was
56+
not replayed on a fresh host before this release. The dated macOS arm64/HVF and
57+
Ubuntu amd64/KVM evidence remains listed on the
58+
[Status](../../docs/about/status/) page; source, package, release, and
59+
native-host evidence remain separate gates.
60+
61+
## Install or upgrade
62+
63+
Download the installer and assets from the
64+
[Farrow 0.4.0 GitHub Release](https://github.com/pgsty/farrow/releases/tag/v0.4.0):
65+
66+
```bash
67+
curl -fLO https://github.com/pgsty/farrow/releases/download/v0.4.0/install.sh
68+
chmod +x install.sh
69+
FARROW_VERSION=0.4.0 ./install.sh
70+
farrow version
71+
farrow doctor
72+
```
73+
74+
Homebrew formula and amd64/arm64 DEB/RPM packages are attached to the same
75+
pre-release. Existing deployment and Catalog state remains readable.

‎content/blog/release/farrow-0.4.0.zh.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
---
2+
title: "Farrow 0.4.0：一条命令、能用的数据盘、统一的输出"
3+
linkTitle: Farrow 0.4.0
4+
description: 首次运行只需一条命令，默认数据盘在所有镜像上可用，就绪失败直接给出原因，全部命令统一输出风格。
5+
date: 2026-09-02
6+
weight: 1
7+
categories: [发布]
8+
tags: [Farrow 0.4.0, QEMU, 体验, 发布]
9+
icon: fa-solid fa-rocket
10+
---
11+
12+
Farrow 0.4.0 是当前公开的 pre-1.0 发布。它把首次运行压缩为一条命令，修复了 Debian 与
13+
Ubuntu 镜像上的默认数据盘，并让全部命令使用同一套输出风格。Pigsty Inventory 格式、
14+
固定 IP Deployment 模型、状态布局与内嵌 Catalog revision `2026082903` 均未变化。
15+
16+
## 变化
17+
18+
- 在终端里，固定 IP 网络尚未安装时 `farrow up` 会自己执行 `farrow setup`：展示 setup
19+
计划、在特权步骤前确认，然后继续。`farrow init` 的下一步提示改为 `farrow up`。
20+
- `vm_disks[].fs` 默认值改为 `auto`：空白磁盘在 Guest 有 `mkfs.xfs` 时格式化为 XFS，
21+
否则为 ext4，与 Pigsty 的 Vagrant 流程一致。旧的 `xfs` 默认值在不带 xfsprogs 的
22+
Debian 与 Ubuntu 镜像上会失败。按旧默认值创建的 Deployment 不会被报告为漂移，持久盘
23+
也保持兼容。
24+
- Guest 的错误标记携带失败命令的最后一行输出，`up` 会报告
25+
`guest bootstrap failed during data-disks: xfs requested but mkfs.xfs is unavailable`，
26+
而不是只有退出码。
27+
- 生命周期命令与 `status` 打印节点表，`up` 成功后给出 `next: farrow ssh <node>`。
28+
没有变化时 `plan` 与 `validate` 只打印一行；`image list`、`network status`、`doctor`
29+
与预检错误使用没有机器码的自然语句；`spec hash` 等内部信息只在 `--json` 中出现。
30+
未知节点名的错误会列出现有节点。
31+
- `farrow ssh <node> -- 'df -h /data; id'` 会把远程命令按 OpenSSH 的方式原样传递。
32+
33+
## 升级说明
34+
35+
由 0.3.0 或更早版本创建、`/data` 从未挂载的 d13、d12 或 Ubuntu 节点，运行一次
36+
`farrow recreate <node>` 即可；这些镜像上磁盘会格式化为 ext4，Enterprise Linux 镜像上
37+
为 XFS。在没有终端的自动化中，对未准备好的宿主机运行 `up` 之前仍需先执行
38+
`farrow setup --yes`。
39+
40+
## 验证边界
41+
42+
源码 Commit `8ecb8476c7dbc934d8cbbee935ac53884d00fcdb` 通过完整本地源码门禁：单测与
43+
Race、Vet、Staticcheck、deadcode、errcheck、`govulncheck`、Shell 与模块检查、四目标
44+
构建、镜像流水线与 Installer 边界、依赖许可证。Tag 工作流在公开 Release 前重复执行了
45+
这些检查，并构建、验证了全部 Archive、原生 Package、SBOM 与 Installer。
46+
47+
新的首次运行路径（`up` 自动执行 `setup`）有单元测试覆盖，但本次发布前未在全新宿主机上
48+
重放。带日期的 macOS arm64/HVF 与 Ubuntu amd64/KVM 证据仍列在[状态页](../../docs/about/status/)；
49+
源码、打包、发布与真机证据继续作为独立门禁。
50+
51+
## 安装或升级
52+
53+
从 [Farrow 0.4.0 GitHub Release](https://github.com/pgsty/farrow/releases/tag/v0.4.0)
54+
下载 Installer 与资产：
55+
56+
```bash
57+
curl -fLO https://github.com/pgsty/farrow/releases/download/v0.4.0/install.sh
58+
chmod +x install.sh
59+
FARROW_VERSION=0.4.0 ./install.sh
60+
farrow version
61+
farrow doctor
62+
```
63+
64+
同一 Pre-release 附带 Homebrew Formula 与 amd64/arm64 DEB/RPM 软件包。现有 Deployment 与
65+
Catalog 状态仍可读取。

‎content/docs/about/status.md‎

Lines changed: 12 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -11,10 +11,10 @@ and the public site are separate gates. Install instructions are in the
1111
[Quick Start](../../start/tutorial/#install).
1212

1313
The current public release is
14-
[`v0.3.0`](https://github.com/pgsty/farrow/releases/tag/v0.3.0). Its source and
15-
package gates passed at commit `da6d02426da93c677c94c67fec4eb4fcecf4766a`;
14+
[`v0.4.0`](https://github.com/pgsty/farrow/releases/tag/v0.4.0). Its source and
15+
package gates passed at commit `8ecb8476c7dbc934d8cbbee935ac53884d00fcdb`;
1616
the native-host rows below remain the latest dated VM evidence rather than
17-
being implicitly promoted to 0.3.0.
17+
being implicitly promoted to 0.4.0.
1818

1919
## Summary
2020

@@ -49,6 +49,15 @@ custody must be formalized before 1.0.
4949
Each entry belongs to the exact checkpoint exercised that day. Later source or
5050
documentation edits do not inherit native proof without another replay.
5151

52+
### Farrow 0.4.0 release — 2026-09-02
53+
54+
The exact tag commit passed `make check` and the release workflow's archive,
55+
DEB/RPM, SBOM, checksum, installer, Homebrew-formula, and package-parity gates.
56+
`up` now runs `setup` itself on an unprepared terminal host, `vm_disks[].fs`
57+
defaults to `auto`, readiness failures carry the guest's last error line, and
58+
every command shares one output style. The first-run path was not replayed on a
59+
fresh host; no new native VM replay is claimed here.
60+
5261
### Farrow 0.3.0 release — 2026-09-02
5362

5463
The exact tag commit passed `make check` and the release workflow's archive,

‎content/docs/about/status.zh.md‎

Lines changed: 10 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -9,9 +9,9 @@ aliases: [/docs/project/, /docs/project/status/, /docs/project/roadmap/, /docs/p
99
Farrow 仍是 pre-1.0。源码测试、带日期的真机重放、软件包、发布、CI 与线上站点是不同门禁。
1010
安装方法见[快速上手](../../start/tutorial/#安装)。
1111

12-
当前公开版本为 [`v0.3.0`](https://github.com/pgsty/farrow/releases/tag/v0.3.0)。其源码与
13-
Package 门禁在 Commit `da6d02426da93c677c94c67fec4eb4fcecf4766a` 通过；下表真机记录
14-
仍是最新的带日期 VM 证据，不会被自动提升为 0.3.0 证据。
12+
当前公开版本为 [`v0.4.0`](https://github.com/pgsty/farrow/releases/tag/v0.4.0)。其源码与
13+
Package 门禁在 Commit `8ecb8476c7dbc934d8cbbee935ac53884d00fcdb` 通过；下表真机记录
14+
仍是最新的带日期 VM 证据，不会被自动提升为 0.4.0 证据。
1515

1616
## 概览
1717

@@ -43,6 +43,13 @@ Package 门禁在 Commit `da6d02426da93c677c94c67fec4eb4fcecf4766a` 通过；下
4343

4444
每条记录只属于当天真正执行过的准确 Checkpoint；后续源码或文档修改不会自动继承真机证明。
4545

46+
### Farrow 0.4.0 发布：2026-09-02
47+
48+
精确 Tag Commit 通过 `make check`，以及发布工作流的 Archive、DEB/RPM、SBOM、Checksum、
49+
Installer、Homebrew Formula 与 Package 一致性门禁。`up` 在未准备好的终端宿主机上会自己
50+
执行 `setup`，`vm_disks[].fs` 默认为 `auto`，就绪失败携带 Guest 最后一行错误，全部命令
51+
共享一套输出风格。首次运行路径未在全新宿主机上重放；本节不声称新增真机 VM 重放。
52+
4653
### Farrow 0.3.0 发布：2026-09-02
4754

4855
精确 Tag Commit 通过 `make check`，以及发布工作流的 Archive、DEB/RPM、SBOM、Checksum、

‎content/docs/reference/configuration.md‎

Lines changed: 6 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -79,12 +79,12 @@ vm_disks:
7979
persistent: false
8080
```
8181

82-
`path` is the disk identity and mount point. `fs` is `auto`, `xfs`, or `ext4`;
83-
omitting it retains the released `xfs` default. An explicitly selected `auto`
84-
disk uses XFS when `mkfs.xfs` is available and otherwise uses ext4. Explicit
85-
`xfs` and `ext4` never fall back, and an existing filesystem is preserved.
86-
`persistent: true` survives normal destroy. Use `vm_disks: []` for no extra
87-
disk.
82+
`path` is the disk identity and mount point. `fs` is `auto` (the default), `xfs`,
83+
or `ext4`. A blank `auto` disk is formatted XFS when the guest has `mkfs.xfs`
84+
and ext4 otherwise, which matches what the Vagrant flow did. Explicit `xfs` and
85+
`ext4` never fall back, and an existing filesystem is always preserved.
86+
`persistent: true` keeps the disk across an ordinary destroy; `vm_disks: []`
87+
means no extra disk.
8888

8989
## Shares
9090

‎content/docs/reference/configuration.zh.md‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -70,9 +70,9 @@ vm_disks:
7070
persistent: false
7171
```
7272

73-
`path` 同时是磁盘身份与挂载点；`fs` 为 `auto`、`xfs` 或 `ext4`，省略时保持已发布的
74-
`xfs` 默认值。显式选择的空白 `auto` 磁盘在 `mkfs.xfs` 可用时优先使用 XFS，否则
75-
使用 ext4；显式 `xfs`、`ext4` 不会降级，已有文件系统保持不变。`persistent: true`
73+
`path` 同时是磁盘身份与挂载点；`fs` 为 `auto`（默认）、`xfs` 或 `ext4`。空白的
74+
`auto` 磁盘在 guest 有 `mkfs.xfs` 时格式化为 XFS，否则为 ext4，与 Vagrant 流程的
75+
行为一致；显式 `xfs`、`ext4` 不会降级，已有文件系统保持不变。`persistent: true`
7676
在普通 destroy 后保留；`vm_disks: []` 表示不要额外盘。
7777

7878
## 目录共享

‎content/docs/start/troubleshooting.md‎

Lines changed: 3 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -89,8 +89,9 @@ bootstrap stage:
8989
| `private-network` | the fixed-IP interface never came up; check `farrow network status` |
9090
| `ready` | the ready marker could not be written |
9191

92-
`guest bootstrap failed during data-disks (exit status 1)` names the failing
93-
stage; `guest did not become ready within 3m0s: <last ssh error>` means the
92+
`guest bootstrap failed during data-disks: xfs requested but mkfs.xfs is
93+
unavailable` names the failing stage and the guest's last error line (older
94+
markers without a detail show `(exit status N)` instead); `guest did not become ready within 3m0s: <last ssh error>` means the
9495
guest never answered. Read the guest console and QEMU output, then check the
9596
recorded state:
9697

‎content/docs/start/troubleshooting.zh.md‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -80,7 +80,8 @@ Debian/Ubuntu 使用 `root:<调用者可用组> 4750`。桌面系统通过 ACL
8080
| `private-network` | 固定 IP 网卡未能启用；检查 `farrow network status` |
8181
| `ready` | 无法写入 ready 标记 |
8282

83-
`guest bootstrap failed during data-disks (exit status 1)` 指出失败阶段；
83+
`guest bootstrap failed during data-disks: xfs requested but mkfs.xfs is unavailable`
84+
指出失败阶段与 guest 里最后一行错误（没有 detail 的旧标记只显示 `(exit status N)`）；
8485
`guest did not become ready within 3m0s: <last ssh error>` 表示 Guest 始终没有应答。
8586
先看 Guest 串口与 QEMU 输出，再检查记录的状态：
8687

0 commit comments

Comments
 (0)