1.9 KiB

Raw Blame History

ADR-006: Package Versioning Strategy

Date: 2026-05-15
Status: Decided
Deciders: Kevin Adams

Context

The package has historically had version strings tied to specific Proxmox or TrueNAS releases (e.g., ZFSPlugin-8.0.5_1.pm.patch, pvemanagerlib-7.4-3_1.js.patch). This creates confusion — users aren't sure if 2.2.0-1 means it works with TrueNAS 2.2 or Proxmox 2.2.

Decision

The package version is independent of both Proxmox VE and TrueNAS versions.

Package version: semantic versioning MAJOR.MINOR.PATCH (e.g., 3.0.0, 3.1.2)
Supported Proxmox VE versions and TrueNAS versions are documented in:
- GitHub Release notes (the primary place — visible when users click on a release)
- The Description field in DEBIAN/control
- README.md compatibility table

Version Scheme

Series	Meaning
`2.x.x`	Current approach (ZFSPlugin.pm patch wedge)
`3.x.x`	New `TrueNASPlugin` custom storage type
`3.0.x`	Patch releases for 3.0 (bug fixes, no new features)
`3.1.x`	Next minor — could add features like snapshot support

GitHub Release Notes Template

Each release on GitHub should include:

## freenas-proxmox v3.0.0

### Supported Proxmox VE Versions
- Proxmox VE 8.0, 8.1, 8.2, 8.3

### Supported TrueNAS Versions  
- TrueNAS CORE 13.0-U6+
- TrueNAS SCALE 23.10+, 24.04+

### What's New
- ...

### Breaking Changes from v2.x
- Storage type changes from `ZFS over iSCSI (freenas provider)` to `TrueNAS (API)`
- Migration guide: [link]

CI Version Injection

The version is set in one place: a VERSION file or git tag at the repo root. CI reads it and injects via envsubst into packaging/DEBIAN/control.j2.

Branch-to-channel mapping (not version mapping):

feature_* → alpha channel
master → beta/testing channel
Tagged release (v3.0.0) → stable channel

1.9 KiB Raw Blame History