mirror of https://github.com/TheGrandWazoo/freenas-proxmox.git synced 2026-09-30 03:51:27 +02:00

Files

T

Kevin AdamsandClaude Sonnet 5 8a4750378c feat: adopt role-based branching strategy (ADR-013)

release/3.x -> main, release/4.x -> next, master -> archive/v2-legacy
(retired, was byte-identical to release/2.x). Branch identity is now
role-based, not version-numbered -- main and next are fixed names
that never get renamed at a major-version cutover; release/N.x is
reserved exclusively for already-superseded majors, created only at
the moment they're archived.

This directly fixes the structural cause of the bug found 2026-08-30:
build.yml hardcoded literal branch-name comparisons for the
testing/beta channel, and ADR-006's original "master -> beta channel"
rule was never superseded when release/3.x took over as the active
branch, leaving master as a silent, stale duplicate of release/2.x
that CI still treated as a legitimate publish source. Rewrote the
version-resolution logic to match roles instead: refs/heads/main,
refs/heads/next, and a refs/heads/release/*.x pattern that auto-
catches any future archived major with zero code changes needed.
Also tightened the push/PR triggers from a bare wildcard to an
explicit allowlist, and switched the release-notes CHANGELOG link to
a tag-relative permalink instead of a floating branch reference.

Research (DEP-14, openedx/frontend-base #273, semantic-release's
branch-pattern config) is cited in ADR-013; the openedx precedent in
particular fixed this identical bug the same way.

Co-Authored-By: Claude Sonnet 5 <noreply@anthropic.com>

2026-08-30 09:43:33 -04:00

9.1 KiB

Raw Permalink Blame History

freenas-proxmox / truenas-proxmox — Roadmap

This file captures release scope, business decisions, and deferred items. It is updated in the same commit as any scope or decision change — not just in issues or memory.

Released — v3.0.0 (TrueNAS Custom Plugin)

Released: 2026-05-31
Branch: release/3.x (default branch at the time; renamed to main 2026-08-30, see ADR-013)
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v3.0.0

Full rewrite as a native PVE::Storage::Custom plugin. No patching of PVE files, no SSH, full TrueNAS REST API, bearer token auth only.

Confirmed tested

Component	Versions
Proxmox VE	8.4.x, 9.2.x
TrueNAS CORE	13.0-U6
TrueNAS SCALE	24.10 Electric Eel, 25.04, 25.10

What shipped

#	Fix
#266	PVE 9: `lun` string vs integer in QEMU blockdev JSON
#269	SCALE 25.10 strict Pydantic rejects volsize as string
#267	free_image 422 on targetextent delete when VM is running
#265	Loop over all targetextent rows in free_image
#264	SCALE 25.04 integer type coercion + alias uniqueness
#261	API token keyfile (`/etc/pve/priv/truenas-<id>.key`)
#262	Package rename: `freenas-proxmox` → `truenas-proxmox` + transitional package
#263	Fix `truenas_target` full-IQN match
#260	TPM state disk limitation callout
#250	Rollback orphaned TrueNAS resources on `alloc_image` partial failure
#228	Migration docs: beginner, advanced, troubleshooting

Released — GitHub Pages APT Repository

Completed: 2026-06-06
Closed: #230
URL: https://thegrandwazoo.github.io/freenas-proxmox

Replaced Cloudsmith as the primary package distribution channel. Per-major-version dist tracks prevent silent cross-version upgrades (ADR-010). Optional feature packages distributed via apt components (ADR-011).

Dist tracks

Dist	Content	Sources.list
`main`	v2.x — backward-compat alias	`... freenas-proxmox main main`
`v2`	v2.x — explicit pin	`... freenas-proxmox v2 main`
`v3`	v3.x	`... freenas-proxmox v3 main`
`testing`	beta builds	Future — #272

Components (ADR-011)

Component	Content
`main`	Base plugin (all installs)
`multipath`	`truenas-proxmox-multipath` — optional add-on, #256

Cloudsmith transition state (2026-06-06)

Channel	State
Stable (`truenas-proxmox`)	v3.x+ no longer published here; v2.x still published
Testing (`truenas-proxmox-testing`)	Still active until #272 ships

Migration tooling

scripts/migrate-repo-to-github-pages.sh — auto-detects installed version, finds Cloudsmith sources by URL content, switches to correct dist track. Run on each Proxmox node as root.

Deferred Business Decisions

GitHub Repo Rename: `freenas-proxmox` → `truenas-proxmox`

Status: Deferred — no timeline set
Decision date: 2026-05-25
Tracked in: #229

All code is ready. GitHub auto-redirects old URLs so there is no technical urgency.

gh repo rename truenas-proxmox --repo TheGrandWazoo/freenas-proxmox

Note: FUNDING.yml is tied to the user account, not the repo name. Rename has no effect on GitHub Sponsors.

Released — v3.1.0 (PVE 9 + Snapshots)

Released: 2026-06-07
PVE support: PVE 9.x only — PVE 8 support dropped
Decision date: 2026-05-31 — see ADR-009
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v3.1.0

v3.1 is the first release that requires PVE 9. Dropping PVE 8 allows:

Bumping api() to PVE 9's APIVER (silences "older storage API" warning)
Implementing snapshot-as-volume-chains (PVE 9 feature)
Removing the qemu_blockdev_options override if Proxmox fixes Plugin.pm upstream

Completed in v3.1.0

#	Title	Commit
#270	Bump `api()` to 14 — silences PVE 9 "older storage API" warning	`fc74a42`
#272	GitHub Pages testing dist track (retires Cloudsmith testing)	`03fe20b`
#273	Debian changelog in package (`apt changelog` was failing)	`1c98591`
#274	Filename: prefix stripped from Packages — packages not downloadable	`19a3ec2`
#275	README badges pointed to non-existent repo	`da0aaff`
#276	parse_volname state volume crash — RAM snapshots left orphans	`80a7889`
#234	Snapshot interface — ZFS snapshots via TrueNAS REST API	`59d8a81`

Snapshot implementation (2026-06-07): Verified on PVE 9.2.3 against TrueNAS CORE 13.0-U6 and SCALE 24.10. Disk-only and RAM snapshots both confirmed working end-to-end including rollback.

Carried forward

#	Title	Notes
#277	iSCSI GET_LBA_STATUS error on VM start	Log noise, non-fatal — open

Released — v3.2.0 (Multipath)

Released: 2026-06-20
GitHub Release: https://github.com/TheGrandWazoo/freenas-proxmox/releases/tag/v3.2.0

Introduces the truenas-proxmox-multipath optional add-on package. Active-active iSCSI multipath via dm-multipath. Separate plugin (TrueNASMultipath.pm) in the multipath apt component — not part of the base plugin. See ADR-011.

Confirmed tested

Component	Versions
Proxmox VE	9.2.x
TrueNAS CORE	13.0-U6 (FreeBSD / ALUA)
TrueNAS SCALE	24.10 Electric Eel, 25.04

Path mode: Active-active (multibus + service-time 0) — both paths carry I/O simultaneously. Failover and path recovery confirmed on CORE and SCALE 25.04.

What shipped

#	Title	Commit
#256	Multipath plugin — `truenas-proxmox-multipath` package (ADR-011)	`da82356`
#278	Multipath UI panel (`truenas-multipath` in Datacenter → Storage → Add)	`da82356`
#279	postinst: strip pre-existing unmanaged devices block in multipath.conf	`b7acb60`

Known differences: CORE vs SCALE multipath

	TrueNAS CORE (FreeBSD)	TrueNAS SCALE (Linux)
iSCSI target	`ctld`	Linux LIO
ALUA	Yes — `hwhandler='1 alua'`, `prio=50`	No — `hwhandler='0'`, `prio=1`
Portal config	`0.0.0.0` (all interfaces)	Per-IP listen addresses required
Failover time	~2s (ALUA state query)	<0.1s
SCALE 25.04 note	—	`port` field rejected in `PUT /api/v2.0/iscsi/portal` — omit it (#280)

Upcoming — v4.0.0 (WebSocket API, SCALE 25.x)

Target: After PoC testing on SCALE 25.04+
Why major version: WebSocket JSON-RPC 2.0 is a new transport — genuine architectural change.

#	Title
#243	WebSocket JSON-RPC 2.0 API support (TrueNAS SCALE 25.04+)

Ideas under consideration (not committed)

#	Title	Notes
#289	UI: show installed plugin + TrueNAS version per storage	Floated 2026-08-30 alongside #243/ADR-012 work — a per-node plugin version and per-storage TrueNAS version could differ across a cluster, similar to how Ceph's panel surfaces per-node version info. Possible v4.0.0 scope, backported to v3.x if small enough.

Process Rules

Every business decision (defer, hold, change scope) is recorded here and as a comment on the relevant GitHub issue — not only in conversation or AI memory.
ADRs (in .claude/cos/adrs/) capture architectural decisions.
This file captures timing, business rationale, and deferred actions.

9.1 KiB Raw Permalink Blame History

freenas-proxmox / truenas-proxmox — Roadmap

Released — v3.0.0 (TrueNAS Custom Plugin)

Confirmed tested

What shipped

Released — GitHub Pages APT Repository

Dist tracks

Components (ADR-011)

Cloudsmith transition state (2026-06-06)

Migration tooling

Deferred Business Decisions

GitHub Repo Rename: freenas-proxmox → truenas-proxmox

Released — v3.1.0 (PVE 9 + Snapshots)

Completed in v3.1.0

Carried forward

Released — v3.2.0 (Multipath)

Confirmed tested

What shipped

Known differences: CORE vs SCALE multipath

Upcoming — v4.0.0 (WebSocket API, SCALE 25.x)

Ideas under consideration (not committed)

Process Rules

9.1 KiB

Raw Permalink Blame History

GitHub Repo Rename: `freenas-proxmox` → `truenas-proxmox`